starred/json
1
0
Fork 0
mirror of https://github.com/nlohmann/json.git synced 2026-10-06 06:14:51 +01:00
Code Issues Packages Projects Releases 10 Wiki Activity

deploy: d8d47be4a5

Browse Source
This commit is contained in:
nlohmann
2026-10-04 15:46:44 +00:00
parent 19f538472d
commit c51ca275d0
374 changed files with 1998 additions and 551 deletions
Download Patch File Download Diff File Expand all files Collapse all files
api/basic_json/to_bson/index.md
+10 -3
View File
@@ -2,11 +2,14 @@
```
// (1)
static std::vector<std::uint8_t> to_bson(const basic_json& j);
static std::vector<std::uint8_t> to_bson(const basic_json& j,
const error_handler_t error_handler = error_handler_t::keep);
// (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);
static void to_bson(const basic_json& j, detail::output_adapter<std::uint8_t> o,
const error_handler_t error_handler = error_handler_t::keep);
static void to_bson(const basic_json& j, detail::output_adapter<char> o,
const error_handler_t error_handler = error_handler_t::keep);
```
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).
@@ -22,6 +25,8 @@ The exact mapping and its limitations are described on a [dedicated page](https:
`o` (in) : output adapter to write serialization to
`error_handler` (in) : how to treat a string or object key in `j` that is not valid UTF-8; see [`error_handler_t`](https://json.nlohmann.me/api/basic_json/error_handler_t/index.md). The default, `keep`, writes the ill-formed bytes to the output as is, as every version of `to_bson` did before this parameter was added; `strict` throws; `replace`/`ignore` sanitize it the same way [`dump`](https://json.nlohmann.me/api/basic_json/dump/index.md) would. If [`JSON_STRICT_BINARY_UTF8`](https://json.nlohmann.me/api/macros/json_strict_binary_utf8/index.md) is enabled, the default is `strict` instead.
## Return value
1. BSON serialization as a byte vector
@@ -37,6 +42,7 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
- Throws [`out_of_range.409`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range409) if 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.412`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range412) if 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.415`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range415) if 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)"`
- Throws [type_error.316](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error316) if a string or object key is not valid UTF-8 and `error_handler` is `strict` (the default only if [`JSON_STRICT_BINARY_UTF8`](https://json.nlohmann.me/api/macros/json_strict_binary_utf8/index.md) is enabled)
## Complexity
@@ -130,3 +136,4 @@ Output:
- Throws `out_of_range.412` and `out_of_range.415` since version 3.13.0 unreleased.
- Linear in the size of `j`, and no longer limited by the call stack for deeply nested values, since version 3.13.0 unreleased.
- `out_of_range.415` is now detected before anything is written, like the other exceptions above, since version 3.13.0 unreleased.
- Added `error_handler` parameter in version 3.13.0 unreleased. Its default, `keep`, writes the bytes of a string or object key that is not valid UTF-8 unchanged, as before; `strict` (the default if [`JSON_STRICT_BINARY_UTF8`](https://json.nlohmann.me/api/macros/json_strict_binary_utf8/index.md) is enabled) throws `type_error.316` before anything is written.