mirror of
https://github.com/nlohmann/json.git
synced 2026-10-16 19:18:12 +00:00
Niels Lohmann
419e1678ee
Squashed onto develop cd6b428ef (CI fixes from #5860). Original commits:
- Fix silent wrong results for custom number types
- Fix CI: build the out_of_range.407 message from string_t and fix a link
- Fix CI: diagnostics message, clang-tidy, and MinGW section limit
- Format the out_of_range.407 number without dump()
- Move the std::deque array test out of unit-regression3.cpp
- Fix clang-tidy and clang 3.4/3.5 failures in the custom number type changes
- Fix CI: cast the 128-bit unsigned value explicitly in the integer fast path
Signed-off-by: Niels Lohmann <mail@nlohmann.me>
2.9 KiB
2.9 KiB
nlohmann::basic_json::to_bon8
// (1)
static std::vector<std::uint8_t> to_bon8(const basic_json& j);
// (2)
static void to_bon8(const basic_json& j, detail::output_adapter<std::uint8_t> o);
static void to_bon8(const basic_json& j, detail::output_adapter<char> o);
Serializes a given JSON value j to a byte vector using the BON8 (Binary Object Notation 8) serialization format. BON8
is a compact binary serialization format that stores strings as UTF-8 without a length prefix.
- Returns a byte vector containing the BON8 serialization.
- Writes the BON8 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
- BON8 serialization as a byte vector
- (none)
Exception safety
Strong guarantee: if an exception is thrown, there are no changes in the JSON value j, which is never modified.
With (2), the bytes written before the exception remain in the output adapter.
Exceptions
- Throws out_of_range.407 if
jcontains an integer outside the range of int64 (an unsigned integer above 9223372036854775807, or, with a number type wider than 64 bits, any integer beyond int64), which BON8 cannot represent - Throws type_error.316 if
jcontains a string that is not valid UTF-8 - Throws type_error.321 if
jor a value nested in it is discarded; example:"cannot serialize discarded value to BON8"
Complexity
Linear in the size of the JSON value j.
Examples
??? example "Example: serialize a JSON value to BON8"
The example shows the serialization of a JSON value to a byte vector in BON8 format.
```cpp
--8<-- "examples/to_bon8.cpp"
```
Output:
```json
--8<-- "examples/to_bon8.output"
```
??? example "Example: type_error.316 exception"
The example shows how serializing a string that is not valid UTF-8 throws an exception, because BON8 stores strings
as UTF-8.
```cpp
--8<-- "examples/to_bon8__exception.cpp"
```
Output:
```json
--8<-- "examples/to_bon8__exception.output"
```
See also
- from_bon8 create a JSON value from an input in BON8 format
- to_cbor create a CBOR serialization of a JSON value
- to_msgpack create a MessagePack serialization of a JSON value
- to_bson create a BSON 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.13.0.