From 693cc887582a7be3c41cb617c02a9759c204738a Mon Sep 17 00:00:00 2001 From: Niels Lohmann Date: Wed, 19 Aug 2026 20:44:20 +0200 Subject: [PATCH] Document JSON_USE_SIMDUTF on the macro overview page The macro was only listed in the API macro index; add it to the supported macros overview alongside the other JSON_USE_* macros, and note that it selects between two definitions of the same inline function and so must be defined identically in every translation unit. Signed-off-by: Niels Lohmann --- docs/mkdocs/docs/api/macros/json_use_simdutf.md | 7 +++++++ docs/mkdocs/docs/features/macros.md | 8 ++++++++ 2 files changed, 15 insertions(+) diff --git a/docs/mkdocs/docs/api/macros/json_use_simdutf.md b/docs/mkdocs/docs/api/macros/json_use_simdutf.md index 097ce795b..c1bb4da12 100644 --- a/docs/mkdocs/docs/api/macros/json_use_simdutf.md +++ b/docs/mkdocs/docs/api/macros/json_use_simdutf.md @@ -18,6 +18,13 @@ 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. +!!! 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. diff --git a/docs/mkdocs/docs/features/macros.md b/docs/mkdocs/docs/features/macros.md index 1d169fdeb..c4602fa5a 100644 --- a/docs/mkdocs/docs/features/macros.md +++ b/docs/mkdocs/docs/features/macros.md @@ -137,6 +137,14 @@ behavior is deprecated and switched off (`0`) by default. See [full documentation of `JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON`](../api/macros/json_use_legacy_discarded_value_comparison.md). +## `JSON_USE_SIMDUTF` + +When defined, UTF-8 validation of JSON strings read from contiguous byte input is delegated to the +[simdutf](https://github.com/simdutf/simdutf) library instead of the built-in scalar validator. This is an opt-in +external dependency and is not defined by default. + +See [full documentation of `JSON_USE_SIMDUTF`](../api/macros/json_use_simdutf.md). + ## `NLOHMANN_DEFINE_TYPE_*(...)`, `NLOHMANN_DEFINE_DERIVED_TYPE_*(...)` The library defines 12 macros to simplify the serialization/deserialization of types. See the page on