# JSON_USE_SIMDUTF

```
#define JSON_USE_SIMDUTF
```

When defined, the parser validates the UTF-8 content of JSON strings that come from a **contiguous byte input** (`std::string`, `std::vector<char>`/`<std::uint8_t>`, string literals, `const char*` ranges, …) using the [simdutf](https://github.com/simdutf/simdutf) library instead of the built-in scalar validator. On text with many non-ASCII characters (e.g. CJK or emoji) this can validate several times faster.

This is an **opt-in external dependency**. The library itself remains header-only and its behavior is unchanged: the same input is accepted or rejected either way, and every parse error is reported at the same position with the same message (simdutf is only used to fast-path *valid* runs; anything it flags falls back to the scalar path so the exact diagnostic is preserved). Streaming inputs (files, `std::istream`, wide strings, user-defined adapters) always use the scalar path.

When `JSON_USE_SIMDUTF` is defined you must make the `simdutf.h` header available on the include path and link the simdutf library. When it is not defined, no simdutf header is included and there is no dependency.

Requires C++17

simdutf requires C++17 and its header rejects older standards with an `#error`. The backend is therefore only compiled in from C++17 on. In C++11 and C++14 the macro has no effect and the scalar validator is used, which accepts and rejects exactly the same input -- only throughput differs. Setting the macro project-wide is therefore safe even when some translation units are built with an older standard.

Define consistently

The macro selects between two definitions of the same inline validation function. It must therefore be defined identically for **every** translation unit that includes the library; mixing translation units that define it with ones that do not is an ODR violation. Prefer setting it as a compile definition on the target rather than with `#define` in individual source files.

## Default definition

By default, `JSON_USE_SIMDUTF` is not defined and the portable C++11 scalar validator is used.

```
#undef JSON_USE_SIMDUTF
```

## Examples

Example

The code below enables the simdutf backend for UTF-8 validation.

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

...
```

The project must also link against simdutf, e.g. with CMake:

```
target_compile_definitions(your_target PRIVATE JSON_USE_SIMDUTF)
target_link_libraries(your_target PRIVATE simdutf::simdutf)
```

Testing this configuration

The unit tests can be built against the simdutf backend with the CMake option `JSON_TestSimdutf` (`OFF` by default), which fetches simdutf and defines `JSON_USE_SIMDUTF` for every test target. The `ci_test_simdutf` target runs the whole test suite in that configuration.

## Version history

- Added in version 3.13.0.