json/docs/mkdocs/docs/api/macros/json_strict_nul_handling.md

JSON_STRICT_NUL_HANDLING

#define JSON_STRICT_NUL_HANDLING /* value */

When defined to 1, a '\0' (NUL) byte in JSON text input is rejected with parse_error.101, like any other unexpected byte, instead of being silently treated as end of input.

The macro only affects the JSON text parser (parse, accept, sax_parse, and operator>>). There are three cases where a NUL byte is still not rejected:

• The binary formats (from_bjdata, from_bon8, from_bson, from_cbor, from_msgpack, from_ubjson) are never affected: there, 0x00 is ordinary data.
• A bare const char* pointer has no length of its own, so its length is still determined with strlen(). The first NUL byte therefore still marks the end of the input, and nothing after it is read.
• One trailing '\0' at the end of a char, wchar_t, char16_t, char32_t, or (C++20) char8_t array (e.g., a string literal) is trimmed; see the warning below.

Default definition

The default value is 0 (disabled — existing behavior is preserved).

#define JSON_STRICT_NUL_HANDLING 0

Notes

!!! note "Background"

By default, a `'\0'` byte anywhere in the input is treated the same as the real end of the input, rather than as
an ordinary (and, outside of a string, invalid) byte. Everything from that byte onward is silently ignored,
without a parse error - including further, otherwise well-formed JSON:

```cpp
json::parse(std::string("123") + '\0');          // == 123, no error
json::parse(std::string("123") + '\0' + "true"); // == 123, the "true" is silently ignored too
```

This falls out of the same convention used when no explicit input length is given at all: parsing from a
`const char*` already stops at the first NUL byte via `strlen()`, since a bare pointer has no length of its own.
The library applies that same NUL-terminated-C-string convention uniformly, rather than only when a length is
genuinely unavailable - so a `std::string`, iterator range, or container whose content happens to include a NUL
byte is affected the same way a raw `const char*` would be (see the
[FAQ entry](../../home/faq.md#nul-bytes-in-the-input) for a fuller explanation).

This was not fixed unconditionally, because doing so is backwards-incompatible for any caller who happens to
depend on the current behavior - even unknowingly, for instance because their input already contains trailing
padding they never noticed was being discarded (see [#5530](https://github.com/nlohmann/json/issues/5530)).
This macro instead offers an opt-in path to the corrected behavior ahead of version 4.0.0, where it is planned to
become the default.

!!! warning "Opt-in only"

This macro must be defined **before** including `<nlohmann/json.hpp>`. Defining it after the include has no
effect.

Enabling it also changes how an array of a text-literal element type (`char`, `wchar_t`, `char16_t`, `char32_t`,
or, since C++20, `char8_t` - including a string literal, e.g. `json::parse("123")` or `json::parse(L"123")`) is
read: such an array normally carries a trailing `'\0'` contributed by the compiler, not by the source text. With
this macro enabled, that one trailing element is trimmed if present so that parsing a string literal keeps
working, for any of these character types; every other element in the array - including any `'\0'` that is not
the very last element - is read as real data and rejected like any other unexpected byte. Arrays of any other
element type (`unsigned char`, `std::uint8_t`, ...), as used for CBOR or MessagePack, are never affected by this
trimming; their full extent - including a genuine trailing `0x00` - is always preserved, in both states of this
macro.

!!! note "ABI compatibility"

The value of this macro is encoded in the [namespace](../../features/namespace.md) (tag `_snul`), resulting in
distinct symbol names. Translation units compiled with and without it can therefore be linked into the same program
without One Definition Rule (ODR) violations, but they cannot exchange instances of library types.

!!! tip "Workaround without the macro"

To reject a NUL byte without enabling this macro, trim your input yourself before calling `parse()`:

```cpp
s.resize(s.find('\0')); // drop everything from the first NUL onward, if any
json::parse(s);
```

Examples

??? example "Example: default behavior (macro not defined)"

Without the macro, a NUL byte silently ends parsing at that point:

```cpp
#include <nlohmann/json.hpp>

using json = nlohmann::json;

int main()
{
    json j = json::parse(std::string("123") + '\0' + "true");
    // j is 123 -- the '\0' and everything after it is silently ignored
}
```

??? example "Example: opt-in strict handling (macro defined to 1)"

With the macro, a NUL byte is rejected like any other unexpected byte:

```cpp
#define JSON_STRICT_NUL_HANDLING 1
#include <nlohmann/json.hpp>

using json = nlohmann::json;

int main()
{
    json j = json::parse(std::string("123") + '\0' + "true");
    // throws parse_error.101 -- the NUL byte is now invalid input,
    // exactly like any other unexpected trailing byte

    json ok = json::parse("123");
    // ok is 123 -- parsing from a string literal still works
}
```

See also

• :simple-cmake: JSON_StrictNulHandling - CMake option to control the macro
• FAQ: NUL bytes in the input
• parse - deserialize from a compatible input
• accept - check if the input is valid JSON
• operator>> - deserialize from stream

Version history

• Added in version 3.13.0.
• Planned to become the default (with the macro removed) in version 4.0.0.