diff --git a/doc/mkdocs/docs/api/basic_json/from_bson.md b/doc/mkdocs/docs/api/basic_json/from_bson.md index 6df74f39c..060b8fc2e 100644 --- a/doc/mkdocs/docs/api/basic_json/from_bson.md +++ b/doc/mkdocs/docs/api/basic_json/from_bson.md @@ -18,6 +18,35 @@ Deserializes a given input to a JSON value using the BSON (Binary JSON) serializ 1. Reads from a compatible input. 2. Reads from an iterator range. +The library maps BSON record types to JSON value types as follows: + +BSON type | BSON marker byte | JSON value type +--------------- | ---------------- | --------------------------- +double | 0x01 | number_float +string | 0x02 | string +document | 0x03 | object +array | 0x04 | array +binary | 0x05 | binary +undefined | 0x06 | still unsupported +ObjectId | 0x07 | still unsupported +boolean | 0x08 | boolean +UTC Date-Time | 0x09 | still unsupported +null | 0x0A | null +Regular Expr. | 0x0B | still unsupported +DB Pointer | 0x0C | still unsupported +JavaScript Code | 0x0D | still unsupported +Symbol | 0x0E | still unsupported +JavaScript Code | 0x0F | still unsupported +int32 | 0x10 | number_integer +Timestamp | 0x11 | still unsupported +128-bit decimal float | 0x13 | still unsupported +Max Key | 0x7F | still unsupported +Min Key | 0xFF | still unsupported + +!!! warning + + The mapping is **incomplete**. The unsupported mappings are indicated in the table above. + ## Template parameters `InputType` @@ -54,6 +83,11 @@ Deserializes a given input to a JSON value using the BSON (Binary JSON) serializ 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`](is_discarded.md). +## Exceptions + +Throws [`parse_error.114`](../../home/exceptions.md#jsonexceptionparse_error114) if an unsupported BSON record type is +encountered. + ## Exception safety Strong guarantee: if an exception is thrown, there are no changes in the JSON value. @@ -78,6 +112,14 @@ Linear in the size of the input. --8<-- "examples/from_bson.output" ``` +## See also + +- [BSON specification](http://bsonspec.org/spec.html) +- [to_bson](to_bson.md) for the analogous serialization +- [to_cbor](to_cbor.md) for the related CBOR format +- [from_msgpack](from_msgpack.md) for the related MessagePack format +- [from_ubjson](from_ubjson.md) for the related UBJSON format + ## Version history - Added in version 3.4.0. diff --git a/include/nlohmann/json.hpp b/include/nlohmann/json.hpp index a06cb4032..3ee4ac4c3 100644 --- a/include/nlohmann/json.hpp +++ b/include/nlohmann/json.hpp @@ -6657,66 +6657,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec } - /*! - @brief Create a JSON value from an input in BSON format - - Deserializes a given input @a i to a JSON value using the BSON (Binary JSON) - serialization format. - - The library maps BSON record types to JSON value types as follows: - - BSON type | BSON marker byte | JSON value type - --------------- | ---------------- | --------------------------- - double | 0x01 | number_float - string | 0x02 | string - document | 0x03 | object - array | 0x04 | array - binary | 0x05 | binary - undefined | 0x06 | still unsupported - ObjectId | 0x07 | still unsupported - boolean | 0x08 | boolean - UTC Date-Time | 0x09 | still unsupported - null | 0x0A | null - Regular Expr. | 0x0B | still unsupported - DB Pointer | 0x0C | still unsupported - JavaScript Code | 0x0D | still unsupported - Symbol | 0x0E | still unsupported - JavaScript Code | 0x0F | still unsupported - int32 | 0x10 | number_integer - Timestamp | 0x11 | still unsupported - 128-bit decimal float | 0x13 | still unsupported - Max Key | 0x7F | still unsupported - Min Key | 0xFF | still unsupported - - @warning The mapping is **incomplete**. The unsupported mappings - are indicated in the table above. - - @param[in] i an input in BSON format convertible to an input adapter - @param[in] strict whether to expect the input to be consumed until EOF - (true by default) - @param[in] allow_exceptions whether to throw exceptions in case of a - parse error (optional, true by default) - - @return deserialized JSON value; in case of a parse error and - @a allow_exceptions set to `false`, the return value will be - value_t::discarded. - - @throw parse_error.114 if an unsupported BSON record type is encountered - - @complexity Linear in the size of the input @a i. - - @liveexample{The example shows the deserialization of a byte vector in - BSON format to a JSON value.,from_bson} - - @sa http://bsonspec.org/spec.html - @sa see @ref to_bson(const basic_json&) for the analogous serialization - @sa see @ref from_cbor(InputType&&, const bool, const bool, const cbor_tag_handler_t) for the - related CBOR format - @sa see @ref from_msgpack(InputType&&, const bool, const bool) for - the related MessagePack format - @sa see @ref from_ubjson(InputType&&, const bool, const bool) for the - related UBJSON format - */ + /// @brief Create a JSON value from an input in BSON format + /// @sa https://json.nlohmann.me/api/basic_json/from_bson/ template JSON_HEDLEY_WARN_UNUSED_RESULT static basic_json from_bson(InputType&& i, @@ -6730,9 +6672,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec return res ? result : basic_json(value_t::discarded); } - /*! - @copydoc from_bson(InputType&&, const bool, const bool) - */ + /// @brief Create a JSON value from an input in BSON format + /// @sa https://json.nlohmann.me/api/basic_json/from_bson/ template JSON_HEDLEY_WARN_UNUSED_RESULT static basic_json from_bson(IteratorType first, IteratorType last, diff --git a/single_include/nlohmann/json.hpp b/single_include/nlohmann/json.hpp index 311097301..43e142d90 100644 --- a/single_include/nlohmann/json.hpp +++ b/single_include/nlohmann/json.hpp @@ -24144,66 +24144,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec } - /*! - @brief Create a JSON value from an input in BSON format - - Deserializes a given input @a i to a JSON value using the BSON (Binary JSON) - serialization format. - - The library maps BSON record types to JSON value types as follows: - - BSON type | BSON marker byte | JSON value type - --------------- | ---------------- | --------------------------- - double | 0x01 | number_float - string | 0x02 | string - document | 0x03 | object - array | 0x04 | array - binary | 0x05 | binary - undefined | 0x06 | still unsupported - ObjectId | 0x07 | still unsupported - boolean | 0x08 | boolean - UTC Date-Time | 0x09 | still unsupported - null | 0x0A | null - Regular Expr. | 0x0B | still unsupported - DB Pointer | 0x0C | still unsupported - JavaScript Code | 0x0D | still unsupported - Symbol | 0x0E | still unsupported - JavaScript Code | 0x0F | still unsupported - int32 | 0x10 | number_integer - Timestamp | 0x11 | still unsupported - 128-bit decimal float | 0x13 | still unsupported - Max Key | 0x7F | still unsupported - Min Key | 0xFF | still unsupported - - @warning The mapping is **incomplete**. The unsupported mappings - are indicated in the table above. - - @param[in] i an input in BSON format convertible to an input adapter - @param[in] strict whether to expect the input to be consumed until EOF - (true by default) - @param[in] allow_exceptions whether to throw exceptions in case of a - parse error (optional, true by default) - - @return deserialized JSON value; in case of a parse error and - @a allow_exceptions set to `false`, the return value will be - value_t::discarded. - - @throw parse_error.114 if an unsupported BSON record type is encountered - - @complexity Linear in the size of the input @a i. - - @liveexample{The example shows the deserialization of a byte vector in - BSON format to a JSON value.,from_bson} - - @sa http://bsonspec.org/spec.html - @sa see @ref to_bson(const basic_json&) for the analogous serialization - @sa see @ref from_cbor(InputType&&, const bool, const bool, const cbor_tag_handler_t) for the - related CBOR format - @sa see @ref from_msgpack(InputType&&, const bool, const bool) for - the related MessagePack format - @sa see @ref from_ubjson(InputType&&, const bool, const bool) for the - related UBJSON format - */ + /// @brief Create a JSON value from an input in BSON format + /// @sa https://json.nlohmann.me/api/basic_json/from_bson/ template JSON_HEDLEY_WARN_UNUSED_RESULT static basic_json from_bson(InputType&& i, @@ -24217,9 +24159,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec return res ? result : basic_json(value_t::discarded); } - /*! - @copydoc from_bson(InputType&&, const bool, const bool) - */ + /// @brief Create a JSON value from an input in BSON format + /// @sa https://json.nlohmann.me/api/basic_json/from_bson/ template JSON_HEDLEY_WARN_UNUSED_RESULT static basic_json from_bson(IteratorType first, IteratorType last,