From 1d51b00830dd1b60d0e1df5bdebe283bbc332d25 Mon Sep 17 00:00:00 2001 From: Niels Lohmann Date: Wed, 22 Jul 2026 10:59:50 +0000 Subject: [PATCH] Reserve output capacity up front for binary serialization The vector-returning to_cbor/to_msgpack/to_ubjson/to_bjdata/to_bson grew the output buffer purely by geometric reallocation. Reserving an estimate up front avoids the early reallocations, which is the dominant per-byte cost for array/object-heavy output. The estimate (binary_reserve_hint) is deliberately conservative and safe against untrusted input: it consults only the top-level element count (O(1), no walk of the DOM), guards the multiplication against overflow, and clamps the result to a fixed 1 MiB ceiling, so a large or hostile DOM can never force an oversized allocation here. The buffer still grows geometrically past the hint, so an underestimate only costs a few later reallocations; scalars/strings/binary are written in one shot and get no hint. Reserving capacity does not change the bytes produced. Throughput (g++/clang -O3, vs the previous commit): cbor int array +10% / +13% cbor object array +20% / +38% Output is byte-for-byte identical to develop across the binary differential corpus. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01XAYM1qhSA2FDaDcGfPW3fG Signed-off-by: Niels Lohmann --- .../nlohmann/detail/output/binary_writer.hpp | 29 ++++++++++++++++ include/nlohmann/json.hpp | 5 +++ single_include/nlohmann/json.hpp | 34 +++++++++++++++++++ 3 files changed, 68 insertions(+) diff --git a/include/nlohmann/detail/output/binary_writer.hpp b/include/nlohmann/detail/output/binary_writer.hpp index 306506801..27122a26b 100644 --- a/include/nlohmann/detail/output/binary_writer.hpp +++ b/include/nlohmann/detail/output/binary_writer.hpp @@ -39,6 +39,35 @@ enum class bjdata_version_t // binary writer // /////////////////// +/*! +@brief conservative capacity hint for binary serialization into a std::vector + +Returns an approximate number of bytes to reserve up front so that serializing +an array/object of many elements does not repeatedly reallocate the output +buffer. Only the top-level element count is consulted (O(1), no walk of the +DOM), and the result is clamped to a fixed ceiling: a large or untrusted DOM can +therefore never trigger an oversized allocation here, and the multiplication +cannot overflow. The buffer still grows geometrically beyond the hint, so a hint +that is too small only costs a few later reallocations. A single scalar, string, +or binary value is written in one shot and needs no hint. +*/ +template +std::size_t binary_reserve_hint(const BasicJsonType& j) +{ + constexpr std::size_t max_hint = static_cast(1) << 20; // 1 MiB + if (j.is_array() || j.is_object()) + { + const std::size_t elements = j.size(); + // guard the multiplication against overflow and cap the reservation + if (elements > max_hint / 4) + { + return max_hint; + } + return (elements * 4) + 2; + } + return 0; +} + /*! @brief serialization to CBOR and MessagePack values */ diff --git a/include/nlohmann/json.hpp b/include/nlohmann/json.hpp index 7eac69de2..002399bc0 100644 --- a/include/nlohmann/json.hpp +++ b/include/nlohmann/json.hpp @@ -4340,6 +4340,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec static std::vector to_cbor(const basic_json& j) { std::vector result; + result.reserve(detail::binary_reserve_hint(j)); detail::binary_writer>( detail::output_vector_sink(result)).write_cbor(j); return result; @@ -4364,6 +4365,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec static std::vector to_msgpack(const basic_json& j) { std::vector result; + result.reserve(detail::binary_reserve_hint(j)); detail::binary_writer>( detail::output_vector_sink(result)).write_msgpack(j); return result; @@ -4390,6 +4392,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec const bool use_type = false) { std::vector result; + result.reserve(detail::binary_reserve_hint(j)); detail::binary_writer>( detail::output_vector_sink(result)).write_ubjson(j, use_size, use_type); return result; @@ -4419,6 +4422,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec const bjdata_version_t version = bjdata_version_t::draft2) { std::vector result; + result.reserve(detail::binary_reserve_hint(j)); detail::binary_writer>( detail::output_vector_sink(result)).write_ubjson(j, use_size, use_type, true, true, version); return result; @@ -4447,6 +4451,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec static std::vector to_bson(const basic_json& j) { std::vector result; + result.reserve(detail::binary_reserve_hint(j)); detail::binary_writer>( detail::output_vector_sink(result)).write_bson(j); return result; diff --git a/single_include/nlohmann/json.hpp b/single_include/nlohmann/json.hpp index fc2ac9811..c9cbb9809 100644 --- a/single_include/nlohmann/json.hpp +++ b/single_include/nlohmann/json.hpp @@ -17049,6 +17049,35 @@ enum class bjdata_version_t // binary writer // /////////////////// +/*! +@brief conservative capacity hint for binary serialization into a std::vector + +Returns an approximate number of bytes to reserve up front so that serializing +an array/object of many elements does not repeatedly reallocate the output +buffer. Only the top-level element count is consulted (O(1), no walk of the +DOM), and the result is clamped to a fixed ceiling: a large or untrusted DOM can +therefore never trigger an oversized allocation here, and the multiplication +cannot overflow. The buffer still grows geometrically beyond the hint, so a hint +that is too small only costs a few later reallocations. A single scalar, string, +or binary value is written in one shot and needs no hint. +*/ +template +std::size_t binary_reserve_hint(const BasicJsonType& j) +{ + constexpr std::size_t max_hint = static_cast(1) << 20; // 1 MiB + if (j.is_array() || j.is_object()) + { + const std::size_t elements = j.size(); + // guard the multiplication against overflow and cap the reservation + if (elements > max_hint / 4) + { + return max_hint; + } + return (elements * 4) + 2; + } + return 0; +} + /*! @brief serialization to CBOR and MessagePack values */ @@ -25846,6 +25875,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec static std::vector to_cbor(const basic_json& j) { std::vector result; + result.reserve(detail::binary_reserve_hint(j)); detail::binary_writer>( detail::output_vector_sink(result)).write_cbor(j); return result; @@ -25870,6 +25900,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec static std::vector to_msgpack(const basic_json& j) { std::vector result; + result.reserve(detail::binary_reserve_hint(j)); detail::binary_writer>( detail::output_vector_sink(result)).write_msgpack(j); return result; @@ -25896,6 +25927,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec const bool use_type = false) { std::vector result; + result.reserve(detail::binary_reserve_hint(j)); detail::binary_writer>( detail::output_vector_sink(result)).write_ubjson(j, use_size, use_type); return result; @@ -25925,6 +25957,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec const bjdata_version_t version = bjdata_version_t::draft2) { std::vector result; + result.reserve(detail::binary_reserve_hint(j)); detail::binary_writer>( detail::output_vector_sink(result)).write_ubjson(j, use_size, use_type, true, true, version); return result; @@ -25953,6 +25986,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec static std::vector to_bson(const basic_json& j) { std::vector result; + result.reserve(detail::binary_reserve_hint(j)); detail::binary_writer>( detail::output_vector_sink(result)).write_bson(j); return result;