Niels Lohmann
d5da84249f
* Skip CBOR tags in front of map keys and validate indefinite text chunks A tag in front of a text string map key was rejected with parse_error.113 even with cbor_tag_handler_t::ignore or store, although tags in front of values are handled. The tags are now skipped iteratively before the key is read; the handler error still rejects them. The chunks of an indefinite-length text string were concatenated before the single UTF-8 check, so a code point split over two chunks, or an invalid chunk, was accepted. RFC 8949, Section 3.2.3 requires every chunk to be valid on its own. With error_handler_t::strict, replace and ignore each chunk is now checked; keep is unchanged. The chunks are appended with append(ptr, len), so StringType needs nothing new. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * docs: correct and extend the CBOR documentation Fix the negative-integer rows (they used MessagePack boundaries), the number_integer range of the 0x1B row, and the half-precision entry in the list of unused types; correct the NaN history (0xF9 since 3.8.0) and the tagged-item wording (only the tag directly in front of a byte string is stored, and only in the 0xD8..0xDB form). Document that to_cbor is not RFC 8949 deterministic, that duplicate keys are accepted (last wins), tags in front of keys, per-chunk UTF-8 validation, the exceptions parse_error.113, out_of_range.406/408 of from_cbor, the pointer and C array input traps, the partially written output on exceptions, and the store/ignore results in the binary values example. Drop the claim that the CBOR reader needs StringType::append(const StringType&) and BinaryType::insert(pos, first, last). Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Regenerate single_include and apply astyle Result of make amalgamate (including make pretty) for the preceding changes. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Address review of the CBOR changes Cite RFC 8949 Section 5.3.1 for duplicate keys, describe the out_of_range.408 condition precisely, rewrap a long line, and update the stale get_string comment (per-chunk UTF-8 check). single_include regenerated. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * docs: drop discarded-value remarks Remove the mention that a discarded value cannot be serialized to CBOR (type_error.321) from the exception-safety and mapping sections. The integer table and all added prose already follow the table-format and Oxford-comma rules. Signed-off-by: Niels Lohmann <mail@nlohmann.me> --------- Signed-off-by: Niels Lohmann <mail@nlohmann.me>
4.1 KiB
4.1 KiB
nlohmann::basic_json::to_cbor
// (1)
static std::vector<std::uint8_t> to_cbor(const basic_json& j,
const error_handler_t error_handler = error_handler_t::keep);
// (2)
static void to_cbor(const basic_json& j, detail::output_adapter<std::uint8_t> o,
const error_handler_t error_handler = error_handler_t::keep);
static void to_cbor(const basic_json& j, detail::output_adapter<char> o,
const error_handler_t error_handler = error_handler_t::keep);
Serializes a given JSON value j to a byte vector using the CBOR (Concise Binary Object Representation) serialization
format. CBOR is a binary serialization format that aims to be more compact than JSON itself, yet more efficient to
parse.
- Returns a byte vector containing the CBOR serialization.
- Writes the CBOR 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
error_handler(in)- how to treat a string or object key in
jthat is not valid UTF-8; seeerror_handler_t. The default,keep, writes the ill-formed bytes to the output as is, as every version ofto_cbordid before this parameter was added;strictthrows;replace/ignoresanitize it the same waydumpwould. IfJSON_STRICT_BINARY_UTF8is enabled, the default isstrictinstead.
Return value
- CBOR serialization as a byte vector
- (none)
Exception safety
Strong guarantee: if an exception is thrown, there are no changes in the JSON value. Bytes that were already written to the output adapter are not taken back.
Exceptions
- Throws
out_of_range.407ifjcontains an integer outside [-2^64, 2^64-1], which is only possible with a number type wider than 64 bits; example:"integer number 18446744073709551616 cannot be represented by CBOR as it does not fit [-2^64, 2^64-1]" - Throws type_error.316 if a string or object key in
jis not valid UTF-8 anderror_handlerisstrict(the default only ifJSON_STRICT_BINARY_UTF8is enabled) - Throws type_error.321 if
jor a value nested in it is discarded; example:"cannot serialize discarded value to CBOR"
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 CBOR format.
```cpp
--8<-- "examples/to_cbor.cpp"
```
Output:
```json
--8<-- "examples/to_cbor.output"
```
See also
- from_cbor create a JSON value from an input in CBOR format
- 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
- to_bon8 create a BON8 serialization of a JSON value
Version history
- Added in version 2.0.9.
- Compact representation of floating-point numbers added in version 3.8.0.
- Added
error_handlerparameter in version 3.13.0. Its default,keep, writes the bytes of a string or object key that is not valid UTF-8 unchanged, as before;strict(the default ifJSON_STRICT_BINARY_UTF8is enabled) throwstype_error.316. - Throws
type_error.321for a discarded value since version 3.13.0; previously, a discarded value nested in an array or object was silently skipped, producing invalid CBOR. - Throws
out_of_range.407for integers that do not fit 64 bits since version 3.13.0; previously, integers of a number type wider than 64 bits were silently truncated.