mirror of
https://github.com/nlohmann/json.git
synced 2026-10-02 20:50:32 +00:00
Niels Lohmann
63c10a51fc
* Review and extend the documentation, and check it in CI A review of all documentation pages found factual errors, dead links, missing cross-references, and gaps in examples. This fixes them and adds checks so the same problems are caught automatically. Fixes: - wrong signatures and version histories (operator!= C++20 member, binary() subtype type, get<PointerType>(), JSON_NO_THREAD_LOCAL, ...) - stale descriptions (number parsing since #5283, UBJSON table, SAX example that no longer compiled, tsl::ordered_map advice) - dead internal and external links; repology.org badges (the domain is suspended) replaced by badges that query the registries directly - deprecation notes link the migration guide; the guide itself fixed Additions: - "See also" sections, cross-references, 25 runnable examples, 12 Mermaid diagrams, new API pages for json_pointer::operator<=> and byte_container_with_subtype::operator==/!= - landing page, guides for untrusted input and performance - "unreleased" badge after versions newer than the latest release Checks: - strict documentation build (broken links/anchors fail it); CI and the publish workflow fetch the full history the build needs - weekly external link check, Mermaid syntax check in CI - check_structure.py: example titles, heading levels, alt texts, header links, docset index coverage; its unused-example check works again - all examples produce the same output on every platform Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Keep the customer links that could not be fixed A dead link on the customers page is still the evidence of where the use of the library was documented. Keep the original URLs of the entries without a working replacement (Marne, Cisco Webex Desk Camera, Philips Hue, CyberArk) and exclude exactly these URLs from the link check. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Correct the duplicate-key recipe's claim about SAX positions The SAX interface's key() receives no position either; only parse_error() does. Also note that the recipe does not report the path to the repeated key (see discussion #5085). Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Say the library is available as a single header and mention json_fwd.hpp Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Correct documentation errors found while hunting for bugs - patch/patch_inplace: list the JSON pointer errors parse_error.106-109 and out_of_range.402/404, and quote the actual parse_error.105 message. - unflatten: list parse_error.106/107/108 and out_of_range.404. - to_bson: list out_of_range.415 (binary subtype above 255) and note that 412 and 415 are new in 3.13.0. - to_string: state that string_t must be convertible to std::string, also in the StringType requirements table. - JSON Lines: a `while (input >> j)` loop also throws after the last value for concatenated JSON values; show a loop that works for both. - BON8: a string gets 0xFF only if nothing follows it in the message; a string at the end of an array or object is ended by 0xFE. - custom_string_type.hpp: add operator+=(char), which the "Always required" list asks for (json_pointer::to_string, flatten, unflatten, and diff did not compile), and an ADL int_to_string for diff and items. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Cache the release headers with functools.lru_cache Codacy (Pylint) flagged the mutable default argument that header() used as its cache. functools.lru_cache keeps the same memoization without it. The script's output is unchanged. Signed-off-by: Niels Lohmann <mail@nlohmann.me> --------- Signed-off-by: Niels Lohmann <mail@nlohmann.me>
3.5 KiB
3.5 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" - Throws
out_of_range.415if the subtype of a binary value exceeds 255, the maximum of the BSON binary subtype; example:"subtype 70000 is too large for the BSON binary subtype (max 255)"
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 "Example: serialize a JSON value to BSON"
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"
```
??? example "Example: out_of_range.409 exception"
The example shows how serializing a JSON object whose key contains a null byte (U+0000) throws an exception, because
BSON keys are null-terminated C strings and cannot contain U+0000 themselves.
```cpp
--8<-- "examples/to_bson__exception.cpp"
```
Output:
```json
--8<-- "examples/to_bson__exception.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
- to_bon8 create a BON8 serialization of a JSON value
Version history
- Added in version 3.4.0.
- Throws
out_of_range.412andout_of_range.415since version 3.13.0. - Linear in the size of
j, and no longer limited by the call stack for deeply nested values, since version 3.13.0. out_of_range.415is now detected before anything is written, like the other exceptions above, since version 3.13.0.