mirror of
https://github.com/nlohmann/json.git
synced 2026-10-03 05:00:30 +00:00
Niels Lohmann
95e9a5931c
* Write BSON in linear time, without recursing per nesting level to_bson() had two problems with nested values: - It recursed once per nesting level, so a value nested deeply enough - 100,000 levels on an 8 MiB stack - exhausted the call stack and terminated the process, although parse() accepts such values without complaint. - BSON prefixes every document and array with its length. The writer computed that length by walking the entire value below it, again for every nested document it wrote, which made serializing O(size x depth). A 200-level document took 30 ms instead of 1. Both passes are now iterative, and each length is computed exactly once: - calc_bson_sizes() computes the length of every document and array in one pass, each from the lengths of its entries, into a table ordered the way they are written. - write_bson_document() then writes the document, taking each length from the table. Everything observable is unchanged, as a differential test against develop confirms byte for byte: - The same bytes are written. - A key containing U+0000 still throws out_of_range.409 for the same first key, with the same diagnostics path, before anything is written. - A document too large for BSON still throws out_of_range.412 before anything is written. - A binary subtype above 255 still throws out_of_range.415 after the same partial output. Only the enclosing objects and arrays are kept on a stack, so a flat document allocates nothing for it. Measured against develop (clang -O3, median of 201 runs): flat objects unchanged, flat arrays 37% faster (the array length was computed twice), a nested 3,000-object document 2x faster, a 200-level document 33x faster. to_bson.md documented the quadratic complexity since #5334; it is linear again. Fixes #5392 for BSON, and #5308. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Do not require a default-constructible string_t in the BSON writer GCC 4.9 and MSVC rejected the test's huge_string_t, which has no default constructor; develop never default-constructed string_t here either. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Let the BSON index-name helper only fill its output parameter It returned a reference to the string it filled, so callers held a second name for index_name. Addresses review feedback. Signed-off-by: Niels Lohmann <mail@nlohmann.me> --------- Signed-off-by: Niels Lohmann <mail@nlohmann.me>
2.6 KiB
2.6 KiB
nlohmann::basic_json::to_bson
// (1)
static std::vector<std::uint8_t> to_bson(const basic_json& j);
// (2)
static void to_bson(const basic_json& j, detail::output_adapter<std::uint8_t> o);
static void to_bson(const basic_json& j, detail::output_adapter<char> o);
BSON (Binary JSON) is a binary format in which zero or more ordered key/value pairs are stored as a single entity (a so-called document).
- Returns a byte vector containing the BSON serialization.
- Writes the BSON serialization to an output adapter.
The exact mapping and its limitations are described on a dedicated page.
Parameters
j(in)- JSON value to serialize
o(in)- output adapter to write serialization to
Return value
- BSON serialization as a byte vector
- (none)
Exception safety
Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
Exceptions
- Throws
type_error.317if the top-level type of the JSON value is not an object; example:"to serialize to BSON, top-level type must be object, but is string" - Throws
out_of_range.409if a key in the JSON object contains a null byte (code point U+0000); example:"BSON key cannot contain code point U+0000 (at byte 2)" - Throws
out_of_range.412if the length of a document, array, string, or binary value exceeds the range of the 32-bit BSON length field; example:"BSON length 2147483661 exceeds maximum of 2147483647"
Complexity
Linear in the size of the JSON value j. The length prefixes of all nested documents and arrays are computed in one
pass before anything is written.
Examples
??? example
The example shows the serialization of a JSON value to a byte vector in BSON format.
```cpp
--8<-- "examples/to_bson.cpp"
```
Output:
```json
--8<-- "examples/to_bson.output"
```
See also
- from_bson create a JSON value from an input in BSON format
- to_cbor create a CBOR serialization of a JSON value
- to_msgpack create a MessagePack serialization of a JSON value
- to_ubjson create a UBJSON serialization of a JSON value
- to_bjdata create a BJData serialization of a JSON value
Version history
- Added in version 3.4.0.
- Linear in the size of
j, and no longer limited by the call stack for deeply nested values, since version 3.13.0.