Niels Lohmann
4001fe68b9
Two bugs for custom number types that compile on develop (found while analysing #3578): - compare_integer_with_float() took the signedness of the integer type from std::is_signed, which is false for class types such as absl::int128 or boost::multiprecision::cpp_int. Any float below zero then compared less than every integer, e.g. json(int128(-5)) < json(-2.5) was false. The signedness now comes from std::numeric_limits, like the digits used for the range bound. - With number_integer_t/number_unsigned_t wider than 64 bits (e.g. __int128), CBOR, MessagePack, and BSON silently truncated integers beyond 64 bits (to_cbor of 2^100 read back as 0), BJData truncated unsigned ones with the 'M' marker and could encode truncated ND-array elements and dimensions, and BON8 did not compile (std::to_string is ambiguous for __int128). The writers now throw out_of_range.407 when an integer does not fit the format's range ([-2^64, 2^64-1] for CBOR, [-2^63, 2^64-1] for MessagePack, int64/uint64 for BSON, int64 for BON8); BJData writes such unsigned values as high-precision numbers, as it already did for signed ones and UBJSON does for both, and falls back to a plain object for the ND-array. The checks use std::numeric_limits digits and compile away when the number types are at most 64 bits wide, so the default types pay nothing (the CBOR, MessagePack, and BSON writers compile to identical code). The new unit-custom-number-types.cpp tests the comparison with a small class-type integer and the writers with __int128 where the standard library supports it as an integral type. Signed-off-by: Niels Lohmann <mail@nlohmann.me>
2.7 KiB
2.7 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
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.