wt/json

0 Fork 0

mirror of https://github.com/nlohmann/json.git synced 2026-10-26 12:14:46 +00:00

Files

T

Niels Lohmann 91cc42b302 Document BSON subtype 0x02, document size checks, and lenient reads

Describe the inner length of binary subtype 0x02 that to_bson now writes and
from_bson checks and removes. Add the document size checks (parse_error.112,
not affected by strict=false) to bson.md and from_bson.md, and extend the
list of lenient reads with the UUID and MD5 payload lengths (not checked),
duplicate keys (last value wins), embedded NUL bytes in strings, and the
ignored trailing bytes with strict=false. State that the members of an object
are written in iteration order.

Correct the statement that element names are never validated on read: they
are checked and sanitized like string values by the error handler. Add the
BSON message to the examples of out_of_range.415 and type_error.321, the
subtype limit of 255 to the binary values page, CBOR to the formats that use
byte_container_with_subtype, and fix a typo in the incomplete mapping box.

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

2026-10-26 06:53:06 +01:00

5.8 KiB

Raw Blame History

nlohmann::basic_json::from_bson

// (1)
template<typename InputType>
static basic_json from_bson(InputType&& i,
                            const bool strict = true,
                            const bool allow_exceptions = true,
                            const error_handler_t error_handler = error_handler_t::keep);
// (2)
template<typename IteratorType, typename SentinelType = IteratorType>
static basic_json from_bson(IteratorType first, SentinelType last,
                            const bool strict = true,
                            const bool allow_exceptions = true,
                            const error_handler_t error_handler = error_handler_t::keep);

Deserializes a given input to a JSON value using the BSON (Binary JSON) serialization format.

Reads from a compatible input.
Reads from an iterator range, or an iterator and a sentinel of a different type (C++20 ranges support).

The exact mapping and its limitations are described on a dedicated page.

Template parameters

InputType

A compatible input, for instance:

an std::istream object
a FILE pointer
a C-style array of characters
a pointer to a null-terminated string of single byte characters
a container obj for which begin(obj) and end(obj) produce a valid pair of iterators (as found via ADL or member functions, with semantics compatible to std::begin and std::end)

IteratorType

a compatible iterator type

SentinelType

defaults to IteratorType; may be a different type comparable to IteratorType via operator!=, for instance.

a custom sentinel type for C++20 ranges
std::default_sentinel_t, when IteratorType is std::counted_iterator

Parameters

i (in): an input in BSON format convertible to an input adapter
first (in): iterator to the start of the input
last (in): iterator to the end of the input, or a sentinel value that compares equal to the end iterator with operator!=
strict (in): whether to expect the input to be consumed until EOF (#!cpp true by default)
allow_exceptions (in): whether to throw exceptions in case of a parse error (optional, #!cpp true by default)
error_handler (in): how to treat a string value or object key that is not valid UTF-8; see error_handler_t. BSON does not require a decoder to reject ill-formed UTF-8, so checking is opt-in: the default, keep, does not check at all, as every binary reader did before this parameter was added; strict checks and throws; replace/ignore sanitize the string the same way dump would

Return value

deserialized JSON value; in case of a parse error and allow_exceptions set to #!cpp false, the return value will be value_t::discarded. The latter can be checked with is_discarded.

Exception safety

Strong guarantee: if an exception is thrown, there are no changes in the JSON value.

Exceptions

Throws parse_error.110 if the given input ends prematurely or the end of the input was not reached when strict was set to true
Throws parse_error.112 if a parse error occurs (e.g., an invalid string or byte array length, an invalid inner length of a binary value with subtype 0x02, or a document size that does not match the content; strict does not affect the document size checks)
Throws parse_error.114 if an unsupported BSON record type is encountered
Throws parse_error.113 if a string value or object key is not valid UTF-8 and error_handler is strict

Complexity

Linear in the size of the input.

Examples

??? example

The example shows the deserialization of a byte vector in BSON format to a JSON value.
 
```cpp
--8<-- "examples/from_bson.cpp"
```

Output:

```json
--8<-- "examples/from_bson.output"
```

Version history

Added in version 3.4.0.
Extended container support (1) to include types with lvalue-only ADL begin/end (matching std::begin/std::end semantics) in version 3.13.0.
Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0.
Added error_handler parameter in version 3.13.0.

!!! warning "Deprecation"

- Overload (2) replaces calls to `from_bson` with a pointer and a length as first two parameters, which has been
  deprecated in version 3.8.0. In version 4.0.0, this overload
  will be deleted (`= delete`) rather than removed. Please replace all calls like
  `#!cpp from_bson(ptr, len, ...);` with `#!cpp from_bson(ptr, ptr+len, ...);`.
- Overload (2) replaces calls to `from_bson` with a pair of iterators as their first parameter, which has been
  deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like
  `#!cpp from_bson({ptr, ptr+len}, ...);` with `#!cpp from_bson(ptr, ptr+len, ...);`.

You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated
function.

See the [migration guide](../../integration/migration_guide.md#parsing) for how to update existing code.

5.8 KiB Raw Blame History