wt/json

0 Fork 0

mirror of https://github.com/nlohmann/json.git synced 2026-11-03 13:28:32 +00:00

Files

T

Niels Lohmann 809ace26b3 Keep writing ill-formed UTF-8 unchanged unless JSON_STRICT_BINARY_UTF8 is set

Throwing type_error.316 from to_cbor(), to_ubjson(), to_bjdata(), and
to_bson() by default would break code that works with 3.12.0, for example
code that stores ISO 8859-1 in a string and only writes it to a binary
format. Following the plan for 4.0.0, the check is now opt-in via the new
macro JSON_STRICT_BINARY_UTF8 (default 0), which is planned to become the
default in 4.0.0:

- abi_macros.hpp: default 0 and ABI tag _sbu8; macro_unscope.hpp undefines
  it; CMake option JSON_StrictBinaryUTF8; ABI namespace tests updated.
- binary_writer: the four writers call check_text_utf8(), which checks
  only if the macro is enabled. BON8 always checks, MessagePack never.
- Tests: the strict checks move to unit-binary_utf8_strict.cpp, which
  defines the macro; the per-format tests now check that the default
  writes the bytes unchanged (from_X(to_X(j)) == j).
- Docs: new macro page, macro lists, CMake option, namespace tags, and the
  writer/format pages describe the default and the opt-in.

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

2026-10-02 08:45:32 +02:00

2.9 KiB

Raw Blame History

nlohmann::basic_json::to_ubjson

// (1)
static std::vector<std::uint8_t> to_ubjson(const basic_json& j,
                                           const bool use_size = false,
                                           const bool use_type = false);

// (2)
static void to_ubjson(const basic_json& j, detail::output_adapter<std::uint8_t> o,
                      const bool use_size = false, const bool use_type = false);
static void to_ubjson(const basic_json& j, detail::output_adapter<char> o,
                      const bool use_size = false, const bool use_type = false);

Serializes a given JSON value j to a byte vector using the UBJSON (Universal Binary JSON) serialization format. UBJSON aims to be more compact than JSON itself, yet more efficient to parse.

Returns a byte vector containing the UBJSON serialization.
Writes the UBJSON 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
use_size (in): whether to add size annotations to container types; optional, #!cpp false by default.
use_type (in): whether to add type annotations to container types (must be combined with #!cpp use_size = true); optional, #!cpp false by default.

Return value

UBJSON serialization as a byte vector
(none)

Exception safety

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

Exceptions

Throws other_error.502 if use_type is true and use_size is false.
Throws type_error.316 if a string or object key in j is not valid UTF-8 and JSON_STRICT_BINARY_UTF8 is enabled; otherwise, the bytes are written unchanged

Complexity

Linear in the size of the JSON value j.

Examples

??? example

The example shows the serialization of a JSON value to a byte vector in UBJSON format.
 
```cpp
--8<-- "examples/to_ubjson.cpp"
```

Output:

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

Version history

Added in version 3.1.0.
Throwing type_error.316 for a string or object key that is not valid UTF-8 if JSON_STRICT_BINARY_UTF8 is enabled added in version 3.13.0.

2.9 KiB Raw Blame History