deploy: 4a93aa4e2f

api/macros/index.md

@@ -29,6 +29,7 @@ Some aspects of the library can be configured by defining preprocessor macros **
 - [**JSON_NO_IO**](https://json.nlohmann.me/api/macros/json_no_io/index.md) - switch off functions relying on certain C++ I/O headers
 - [**JSON_SKIP_UNSUPPORTED_COMPILER_CHECK**](https://json.nlohmann.me/api/macros/json_skip_unsupported_compiler_check/index.md) - do not warn about unsupported compilers
 - [**JSON_USE_GLOBAL_UDLS**](https://json.nlohmann.me/api/macros/json_use_global_udls/index.md) - place user-defined string literals (UDLs) into the global namespace
+- [**JSON_USE_SIMDUTF**](https://json.nlohmann.me/api/macros/json_use_simdutf/index.md) - use the simdutf library to accelerate UTF-8 validation
 
 ## Library version
 

api/macros/json_use_simdutf.md

@@ -0,0 +1,71 @@
+# JSON_USE_SIMDUTF
+
+```cpp
+#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.
+
+!!! note "Requires C++17"
+
+    simdutf requires C++17 and its header rejects older standards with an `#!cpp #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.
+
+!!! warning "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
+    `#!cpp #define` in individual source files.
+
+## Default definition
+
+By default, `#!cpp JSON_USE_SIMDUTF` is not defined and the portable C++11 scalar validator is used.
+
+```cpp
+#undef JSON_USE_SIMDUTF
+```
+
+## Examples
+
+??? example
+
+    The code below enables the simdutf backend for UTF-8 validation.
+
+    ```cpp
+    #define JSON_USE_SIMDUTF 1
+    #include <nlohmann/json.hpp>
+
+    ...
+    ```
+
+    The project must also link against simdutf, e.g. with CMake:
+
+    ```cmake
+    target_compile_definitions(your_target PRIVATE JSON_USE_SIMDUTF)
+    target_link_libraries(your_target PRIVATE simdutf::simdutf)
+    ```
+
+!!! hint "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.

api/macros/json_use_simdutf/index.md

@@ -0,0 +1,55 @@
+# 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.