mirror of
https://github.com/nlohmann/json.git
synced 2026-10-12 10:13:13 +00:00
101 lines
4.0 KiB
Markdown
101 lines
4.0 KiB
Markdown
# <small>nlohmann::basic_json::</small>error_handler_t
|
|
|
|
```cpp
|
|
enum class error_handler_t {
|
|
strict,
|
|
replace,
|
|
ignore,
|
|
keep
|
|
};
|
|
```
|
|
|
|
This enumeration is used to choose how to treat ill-formed UTF-8 in a string value or object key:
|
|
|
|
- [`dump`](dump.md) uses it while serializing a `basic_json` value to text.
|
|
- [`to_cbor`](to_cbor.md), [`to_msgpack`](to_msgpack.md), [`to_ubjson`](to_ubjson.md), [`to_bjdata`](to_bjdata.md),
|
|
and [`to_bson`](to_bson.md) use it while serializing a `basic_json` value to that binary format. Their default is
|
|
`keep`, as no binary writer checked before this parameter was added. CBOR, UBJSON, BJData, and BSON require valid
|
|
UTF-8, so for these four the default is `strict` if [`JSON_STRICT_BINARY_UTF8`](../macros/json_strict_binary_utf8.md)
|
|
is enabled; MessagePack's specification explicitly allows a string to contain ill-formed UTF-8, so `to_msgpack`
|
|
stays at `keep`. `to_bon8` does not take this parameter: BON8 always validates, since UTF-8 lead bytes are
|
|
structural to that format.
|
|
- [`from_cbor`](from_cbor.md), [`from_msgpack`](from_msgpack.md), [`from_ubjson`](from_ubjson.md),
|
|
[`from_bjdata`](from_bjdata.md), and [`from_bson`](from_bson.md) use it while parsing that binary format, to decide
|
|
whether to check a string value or object key for well-formed UTF-8 at all; by default (`keep`) they do not, as no
|
|
binary reader did before this parameter was added. `from_bon8` does not take this parameter, for the same reason
|
|
`to_bon8` does not.
|
|
|
|
Four values are differentiated:
|
|
|
|
strict
|
|
: throw a `type_error`/`parse_error` exception in case of invalid UTF-8
|
|
|
|
replace
|
|
: replace invalid UTF-8 sequences with U+FFFD (� REPLACEMENT CHARACTER)
|
|
|
|
ignore
|
|
: ignore invalid UTF-8 sequences; all valid bytes are copied to the output unchanged, and invalid bytes are dropped
|
|
|
|
keep
|
|
: keep invalid UTF-8 sequences unchanged; only meaningful for the binary formats mentioned above, since
|
|
[`dump`](dump.md) itself must produce text, and `keep` there writes the ill-formed bytes to the output as is, so the
|
|
result is then not valid UTF-8 (but still equals the input bytes exactly, including around any well-formed
|
|
characters, which are still escaped as usual)
|
|
|
|
## Examples
|
|
|
|
??? example
|
|
|
|
The example below shows how the different values of the `error_handler_t` influence the behavior of
|
|
[`dump`](dump.md) when reading serializing an invalid UTF-8 sequence.
|
|
|
|
```cpp
|
|
#include <iostream>
|
|
#include <nlohmann/json.hpp>
|
|
|
|
using json = nlohmann::json;
|
|
|
|
int main()
|
|
{
|
|
// create JSON value with invalid UTF-8 byte sequence
|
|
json j_invalid = "ä\xA9ü";
|
|
try
|
|
{
|
|
std::cout << j_invalid.dump() << std::endl;
|
|
}
|
|
catch (const json::type_error& e)
|
|
{
|
|
std::cout << e.what() << std::endl;
|
|
}
|
|
|
|
std::cout << "string with replaced invalid characters: "
|
|
<< j_invalid.dump(-1, ' ', false, json::error_handler_t::replace)
|
|
<< "\nstring with ignored invalid characters: "
|
|
<< j_invalid.dump(-1, ' ', false, json::error_handler_t::ignore)
|
|
<< "\nstring with the invalid byte kept as is (" << j_invalid.dump(-1, ' ', false, json::error_handler_t::keep).size()
|
|
<< " bytes, not valid UTF-8 itself)\n";
|
|
}
|
|
|
|
```
|
|
|
|
Output:
|
|
|
|
```json
|
|
[json.exception.type_error.316] invalid UTF-8 byte at index 2: 0xA9
|
|
string with replaced invalid characters: "ä�ü"
|
|
string with ignored invalid characters: "äü"
|
|
string with the invalid byte kept as is (7 bytes, not valid UTF-8 itself)
|
|
|
|
```
|
|
|
|
## See also
|
|
|
|
- [dump](dump.md) serializes a JSON value, with an `error_handler_t` parameter to configure invalid UTF-8 handling
|
|
- [Handling invalid UTF-8](../../features/serialization.md#handling-invalid-utf-8) - the article on handling invalid UTF-8
|
|
|
|
## Version history
|
|
|
|
- Added in version 3.4.0.
|
|
- Added `keep`, and made this enumeration apply to the binary readers and writers in addition to `dump`, in version
|
|
3.13.0.
|