Scan strings with SSE2, SSSE3, or NEON

The string fast path found the end of a run of plain characters 8 bytes at
a time (SWAR) and validated non-ASCII text one sequence at a time, calling
validate_one_utf8() out of line for each.

The vector code of json_view's scanner, in the new shared header
detail/input/simd_scan.hpp, now does both 16 bytes at a time: SSE2 finds
the end of a run on x86-64, and the UTF-8 check of Keiser and Lemire runs
with NEON on AArch64 and with SSSE3 on x86-64. SSSE3 is not part of x86-64,
so the check is compiled for it with a function attribute and used when the
CPU has it (cached in a constant-initialized atomic), else the scalar check;
code compiled with -mssse3 skips the CPU check. The first word of a run is
still checked with SWAR (the first four with NEON, where a vector mask
costs more), as most keys and short values end there, and the scalar
helpers are always inlined. On anything else, the scalar code is unchanged.

The new macro JSON_NO_SIMD selects the portable code everywhere, including
the SSE2/NEON digit formatting of the floating-point writer. The lexer tests
now also run with JSON_NO_SIMD and, on x86-64, with -mssse3, and a new test
places every byte that ends a run at each offset across several 16-byte
blocks, after ASCII and after CJK text.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

docs/mkdocs/docs/api/macros/index.md

@@ -38,6 +38,7 @@ header. See also the [macro overview page](../../features/macros.md).
 - [**JSON_HAS_THREE_WAY_COMPARISON**](json_has_three_way_comparison.md) - control 3-way comparison support
 - [**JSON_NO_AUTOMATIC_UDLS**](json_no_automatic_udls.md) - do not include the user-defined string literals (UDLs) automatically
 - [**JSON_NO_IO**](json_no_io.md) - switch off functions relying on certain C++ I/O headers
+- [**JSON_NO_SIMD**](json_no_simd.md) - use only portable code instead of vector instructions (SSE2, SSSE3, NEON)
 - [**JSON_NO_THREAD_LOCAL**](json_no_thread_local.md) - switch off the use of `thread_local` storage
 - [**JSON_SKIP_UNSUPPORTED_COMPILER_CHECK**](json_skip_unsupported_compiler_check.md) - do not warn about unsupported compilers
 - [**JSON_USE_GLOBAL_UDLS**](json_use_global_udls.md) - place user-defined string literals (UDLs) into the global namespace

docs/mkdocs/docs/api/macros/json_no_simd.md

@@ -0,0 +1,83 @@
+# JSON_NO_SIMD
+
+```cpp
+#define JSON_NO_SIMD
+```
+
+When defined, the library uses only portable C++ code where it would otherwise use vector instructions: when scanning
+strings during parsing, and when writing floating-point numbers during serialization.
+
+The macro is an escape hatch, for example for toolchains that cannot compile the vector code, for sanitizers or
+analyzers that do not understand it, or to compare the speed of both variants. It does not change any result: values,
+exceptions, and error positions are the same either way. Only the speed differs.
+
+## Default definition
+
+By default, `#!cpp JSON_NO_SIMD` is not defined, and vector instructions are used where the target has them.
+
+```cpp
+#undef JSON_NO_SIMD
+```
+
+## Notes
+
+!!! note "Which instructions are used"
+
+    - **x86-64:** SSE2, which every x86-64 CPU has, finds the end of runs of plain string characters 16 bytes at a time
+      and writes the digits of floating-point numbers. The UTF-8 check of non-ASCII text needs SSSE3, which is not part
+      of x86-64: it is compiled for SSSE3 with a function attribute and used when the CPU has SSSE3 (every x86-64 CPU
+      since about 2011), else the portable check. Code compiled for SSSE3 anyway (e.g., with `-mssse3` or `-march=native`)
+      skips this check of the CPU. 32-bit x86 uses SSE2 for strings when the compiler targets it.
+    - **AArch64:** NEON, which every 64-bit Arm CPU has, checks UTF-8 text and long runs of plain string characters 16
+      bytes at a time, and writes the digits of floating-point numbers. With MSVC, only the floating-point digits use
+      NEON.
+    - **Other targets:** portable code only.
+
+    Strings are only scanned this way for contiguous input and for the characters a `#!cpp std::istream` holds in its
+    stream buffer (see [`JSON_DISABLE_STREAM_BULK_SCAN`](json_disable_stream_bulk_scan.md)); other inputs are read one
+    character at a time.
+
+!!! note "Interaction with `JSON_USE_SIMDUTF`"
+
+    With [`JSON_USE_SIMDUTF`](json_use_simdutf.md), runs of string characters are first validated by simdutf; the code
+    described here is used for what simdutf does not accept, so that errors are reported at the same position.
+    `JSON_NO_SIMD` does not affect simdutf.
+
+!!! warning "Define consistently"
+
+    The macro selects between two definitions of the library's internal scanning and formatting functions. 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.
+
+## Examples
+
+??? example "Example: switching off vector instructions"
+
+    The program parses and serializes the same values with and without the macro:
+
+    ```cpp
+    #define JSON_NO_SIMD
+    #include <iostream>
+    #include <nlohmann/json.hpp>
+
+    using json = nlohmann::json;
+
+    int main()
+    {
+        const json j = json::parse(R"({"name": "日本語 text", "pi": 3.141592653589793})");
+        std::cout << j.dump() << '\n';  // {"name":"日本語 text","pi":3.141592653589793}
+    }
+    ```
+
+## See also
+
+- [**parse**](../basic_json/parse.md) - deserialize from a compatible input
+- [**dump**](../basic_json/dump.md) - serialization
+- [**JSON_USE_SIMDUTF**](json_use_simdutf.md) - use the simdutf library to accelerate UTF-8 validation
+- [**JSON_DISABLE_STREAM_BULK_SCAN**](json_disable_stream_bulk_scan.md) - read a `std::istream` one character at a time
+- [Parsing: input sources and performance](../../features/parsing/index.md#input-sources-and-performance)
+
+## Version history
+
+- Added in version 3.13.0.

docs/mkdocs/docs/api/macros/json_use_simdutf.md

@@ -6,8 +6,9 @@
 
 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.
+[simdutf](https://github.com/simdutf/simdutf) library instead of the built-in validator (which uses SSSE3 or NEON where
+available, see [`JSON_NO_SIMD`](json_no_simd.md)). On text with many non-ASCII characters (e.g. CJK or emoji) this can
+validate faster, depending on the CPU.
 
 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

docs/mkdocs/docs/features/macros.md

@@ -174,6 +174,13 @@ security reasons (e.g., Intel Software Guard Extensions (SGX)).
 
 See [full documentation of `JSON_NO_IO`](../api/macros/json_no_io.md).
 
+## `JSON_NO_SIMD`
+
+When defined, the library uses only portable code instead of vector instructions (SSE2, SSSE3, NEON) for scanning
+strings and writing floating-point numbers. Results are the same either way. It is not defined by default.
+
+See [full documentation of `JSON_NO_SIMD`](../api/macros/json_no_simd.md).
+
 ## `JSON_NO_THREAD_LOCAL`
 
 When defined, the library does not use `#!cpp thread_local` storage. Copying a value and comparing two values then

docs/mkdocs/docs/features/parsing/index.md

@@ -79,6 +79,10 @@ follow the usual `std::streambuf` contract, and
 [`JSON_DISABLE_UNLOCKED_FILE_IO`](../../api/macros/json_disable_unlocked_file_io.md) for programs in which another
 thread must use the same `#!cpp FILE` object while it is parsed.
 
+Where the target has them, strings are scanned with vector instructions: SSE2 on x86-64 (and SSSE3 for UTF-8 text, when
+the CPU has it) and NEON on AArch64. [`JSON_NO_SIMD`](../../api/macros/json_no_simd.md) selects portable code instead,
+again without changing any result.
+
 ## SAX vs. DOM parsing
 
 The library offers two parsing models:

docs/mkdocs/docs/home/architecture.md

@@ -59,7 +59,7 @@ below are relative to `include/nlohmann`.
 |-----------|----------|
 | Value type enumeration | [`detail/value_t.hpp`](https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/value_t.hpp) |
 | Input adapters | [`detail/input/input_adapters.hpp`](https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/input/input_adapters.hpp) |
-| Lexer | [`detail/input/lexer.hpp`](https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/input/lexer.hpp), [`detail/input/number_parse.hpp`](https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/input/number_parse.hpp), [`detail/input/string_scan.hpp`](https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/input/string_scan.hpp) |
+| Lexer | [`detail/input/lexer.hpp`](https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/input/lexer.hpp), [`detail/input/number_parse.hpp`](https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/input/number_parse.hpp), [`detail/input/string_scan.hpp`](https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/input/string_scan.hpp), [`detail/input/simd_scan.hpp`](https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/input/simd_scan.hpp) |
 | Parser | [`detail/input/parser.hpp`](https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/input/parser.hpp) |
 | SAX interface and DOM builders | [`detail/input/json_sax.hpp`](https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/input/json_sax.hpp) |
 | Binary format readers | [`detail/input/binary_reader.hpp`](https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/input/binary_reader.hpp) |

docs/mkdocs/mkdocs.yml

@@ -310,6 +310,7 @@ nav:
           - 'JSON_NO_AUTOMATIC_UDLS': api/macros/json_no_automatic_udls.md
           - 'JSON_NOEXCEPTION': api/macros/json_noexception.md
           - 'JSON_NO_IO': api/macros/json_no_io.md
+          - 'JSON_NO_SIMD': api/macros/json_no_simd.md
           - 'JSON_NO_THREAD_LOCAL': api/macros/json_no_thread_local.md
           - 'JSON_PRECISE_STREAM_POSITION': api/macros/json_precise_stream_position.md
           - 'JSON_SKIP_LIBRARY_VERSION_CHECK': api/macros/json_skip_library_version_check.md