4.2.4

* fixing issue 2549

* saving.

.circleci/config.yml

@@ -1,316 +0,0 @@
-version: 2.1
-
-
-# We constantly run out of memory so please do not use parallelism (-j, -j4).
-
-# Reusable image / compiler definitions
-executors:
-  gcc8:
-    docker:
-      - image: conanio/gcc8
-        environment:
-          CXX: g++-8
-          CC: gcc-8
-          CMAKE_BUILD_FLAGS:
-          CTEST_FLAGS: --output-on-failure
-
-  gcc9:
-    docker:
-      - image: conanio/gcc9
-        environment:
-          CXX: g++-9
-          CC: gcc-9
-          CMAKE_BUILD_FLAGS:
-          CTEST_FLAGS: --output-on-failure
-
-  gcc10:
-    docker:
-      - image: conanio/gcc10
-        environment:
-          CXX: g++-10
-          CC: gcc-10
-          CMAKE_BUILD_FLAGS:
-          CTEST_FLAGS: --output-on-failure
-
-  clang10:
-    docker:
-      - image: conanio/clang10
-        environment:
-          CXX: clang++-10
-          CC: clang-10
-          CMAKE_BUILD_FLAGS:
-          CTEST_FLAGS: --output-on-failure
-
-  clang9:
-    docker:
-      - image: conanio/clang9
-        environment:
-          CXX: clang++-9
-          CC: clang-9
-          CMAKE_BUILD_FLAGS:
-          CTEST_FLAGS: --output-on-failure
-
-  clang6:
-    docker:
-      - image: conanio/clang60
-        environment:
-          CXX: clang++-6.0
-          CC: clang-6.0
-          CMAKE_BUILD_FLAGS:
-          CTEST_FLAGS: --output-on-failure
-
-# Reusable test commands (and initializer for clang 6)
-commands:
-  dependency_restore:
-    steps:
-      - restore_cache:
-          keys:
-            - cmake-cache-{{ checksum "dependencies/CMakeLists.txt" }}
-
-  dependency_cache:
-    steps:
-      - save_cache:
-          key: cmake-cache-{{ checksum "dependencies/CMakeLists.txt" }}
-          paths:
-            - dependencies/.cache
-
-  install_cmake:
-    steps:
-      - run: apt-get update -qq
-      - run: apt-get install -y cmake
-
-  cmake_prep:
-    steps:
-      - checkout
-      - run: mkdir -p build
-
-  cmake_build_cache:
-    steps:
-      - cmake_prep
-      - dependency_restore
-      - run: cmake  -DSIMDJSON_DEVELOPER_MODE=ON $CMAKE_FLAGS -DCMAKE_INSTALL_PREFIX:PATH=destination -B build .
-      - dependency_cache # dependencies are produced in the configure step
-
-  cmake_build:
-    steps:
-      - cmake_build_cache
-      - run: cmake  --build build
-
-  cmake_test:
-    steps:
-      - cmake_build
-      - run: |
-          cd build &&
-          tools/json2json -h &&
-          ctest $CTEST_FLAGS -L acceptance &&
-          ctest $CTEST_FLAGS -LE acceptance -LE explicitonly
-
-  cmake_assert_test:
-    steps:
-      - run: |
-          cd build &&
-          tools/json2json -h &&
-          ctest $CTEST_FLAGS -L assert
-
-  cmake_test_all:
-    steps:
-      - cmake_build
-      - run: |
-          cd build &&
-          tools/json2json -h &&
-          ctest $CTEST_FLAGS -DSIMDJSON_IMPLEMENTATION="haswell;westmere;fallback" -L acceptance -LE per_implementation &&
-          SIMDJSON_FORCE_IMPLEMENTATION=haswell ctest $CTEST_FLAGS -L per_implementation -LE explicitonly &&
-          SIMDJSON_FORCE_IMPLEMENTATION=westmere ctest $CTEST_FLAGS -L per_implementation -LE explicitonly &&
-          SIMDJSON_FORCE_IMPLEMENTATION=fallback ctest $CTEST_FLAGS -L per_implementation -LE explicitonly &&
-          ctest $CTEST_FLAGS -LE "acceptance|per_implementation" # Everything we haven't run yet, run now.
-
-
-  cmake_perftest:
-    steps:
-      - cmake_build_cache
-      - run: |
-          cmake -DSIMDJSON_ENABLE_DOM_CHECKPERF=ON --build  build --target checkperf &&
-          cd build &&
-          ctest --output-on-failure -R checkperf
-
-  # we not only want cmake to build and run tests, but we want also a successful installation from which we can build, link and run programs
-  cmake_install_test: # this version builds, install, test and then verify from the installation
-    steps:
-      - run: cd build && make install
-      - run: echo -e '#include <simdjson.h>\nint main(int argc,char**argv) {simdjson::dom::parser parser;simdjson::dom::element tweets = parser.load(argv[1]); }' > tmp.cpp && c++ -Ibuild/destination/include -Lbuild/destination/lib -std=c++17 -Wl,-rpath,build/destination/lib -o linkandrun tmp.cpp -lsimdjson && ./linkandrun jsonexamples/twitter.json
-
-  cmake_installed_test_cxx20: # assuming that it was installed, this tries to build using C++20
-    steps:
-      - run: echo -e '#include <simdjson.h>\nint main(int argc,char**argv) {simdjson::dom::parser parser;simdjson::dom::element tweets = parser.load(argv[1]); }' > tmp.cpp && c++ -Ibuild/destination/include -Lbuild/destination/lib -std=c++20 -Wl,-rpath,build/destination/lib -o linkandrun tmp.cpp -lsimdjson && ./linkandrun jsonexamples/twitter.json
-
-jobs:
-
-  # static
-  justlib-gcc10:
-    description: Build just the library, install it and do a basic test
-    executor: gcc10
-    environment: { CMAKE_FLAGS: -DSIMDJSON_JUST_LIBRARY=ON }
-    steps: [ cmake_build, cmake_install_test, cmake_installed_test_cxx20 ]
-  assert-gcc10:
-    description: Build the library with asserts on, install it and run tests
-    executor: gcc10
-    environment: { CMAKE_FLAGS: -DSIMDJSON_GOOGLE_BENCHMARKS=OFF -DCMAKE_CXX_FLAGS_RELEASE=-O3 }
-    steps: [ cmake_test, cmake_assert_test ]
-  assert-clang10:
-    description: Build just the library, install it and do a basic test
-    executor: clang10
-    environment: { CMAKE_FLAGS: -DSIMDJSON_GOOGLE_BENCHMARKS=OFF -DCMAKE_CXX_FLAGS_RELEASE=-O3 }
-    steps: [ cmake_test, cmake_assert_test ]
-  gcc10-perftest:
-    description: Build and run performance tests on GCC 10 and AVX 2 with a cmake static build, this test performance regression
-    executor: gcc10
-    environment: { CMAKE_FLAGS: -DSIMDJSON_GOOGLE_BENCHMARKS=OFF -DBUILD_SHARED_LIBS=OFF }
-    steps: [ cmake_perftest ]
-  gcc10:
-    description: Build and run tests on GCC 10 and AVX 2 with a cmake static build
-    executor: gcc10
-    environment: { CMAKE_FLAGS: -DSIMDJSON_GOOGLE_BENCHMARKS=ON -DBUILD_SHARED_LIBS=OFF }
-    steps: [ cmake_test, cmake_install_test, cmake_installed_test_cxx20 ]
-  clang6:
-    description: Build and run tests on clang 6 and AVX 2 with a cmake static build
-    executor: clang6
-    environment: { CMAKE_FLAGS: -DSIMDJSON_GOOGLE_BENCHMARKS=ON -DBUILD_SHARED_LIBS=OFF }
-    steps: [ cmake_test, cmake_install_test ]
-  clang10:
-    description: Build and run tests on clang 10 and AVX 2 with a cmake static build
-    executor: clang10
-    environment: { CMAKE_FLAGS: -DSIMDJSON_GOOGLE_BENCHMARKS=ON  -DBUILD_SHARED_LIBS=OFF }
-    steps: [ cmake_test, cmake_install_test, cmake_installed_test_cxx20 ]
-  # libcpp
-  libcpp-clang10:
-    description: Build and run tests on clang 10 and AVX 2 with a cmake static build and libc++
-    executor: clang10
-    environment: { CMAKE_FLAGS: -DSIMDJSON_USE_LIBCPP=ON  -DBUILD_SHARED_LIBS=OFF }
-    steps: [ cmake_test, cmake_install_test, cmake_installed_test_cxx20 ]
-  # sanitize
-  sanitize-gcc10:
-    description: Build and run tests on GCC 10 and AVX 2 with a cmake sanitize build
-    executor: gcc10
-    environment: { CMAKE_FLAGS: -DCMAKE_BUILD_TYPE=Debug -DBUILD_SHARED_LIBS=ON -DSIMDJSON_SANITIZE=ON, CTEST_FLAGS: --output-on-failure -LE explicitonly }
-    steps: [ cmake_test ]
-  sanitize-clang10:
-    description: Build and run tests on clang 10 and AVX 2 with a cmake sanitize build
-    executor: clang10
-    environment: { CMAKE_FLAGS: -DBUILD_SHARED_LIBS=ON -DSIMDJSON_NO_FORCE_INLINING=ON -DSIMDJSON_SANITIZE=ON, CTEST_FLAGS: --output-on-failure -LE explicitonly }
-    steps: [ cmake_test ]
-  threadsanitize-gcc10:
-    description: Build and run tests on GCC 10 and AVX 2 with a cmake sanitize build
-    executor: gcc10
-    environment: { CMAKE_FLAGS: -DBUILD_SHARED_LIBS=ON -DSIMDJSON_SANITIZE_THREADS=ON, CTEST_FLAGS: --output-on-failure -LE explicitonly }
-    steps: [ cmake_test ]
-  threadsanitize-clang10:
-    description: Build and run tests on clang 10 and AVX 2 with a cmake sanitize build
-    executor: clang10
-    environment: { CMAKE_FLAGS: -DBUILD_SHARED_LIBS=ON  -DSIMDJSON_NO_FORCE_INLINING=ON -DSIMDJSON_SANITIZE_THREADS=ON, CTEST_FLAGS: --output-on-failure -LE explicitonly }
-    steps: [ cmake_test ]
-  # dynamic
-  dynamic-gcc10:
-    description: Build and run tests on GCC 10 and AVX 2 with a cmake dynamic build
-    executor: gcc10
-    environment: { CMAKE_FLAGS: -DBUILD_SHARED_LIBS=ON }
-    steps: [ cmake_test, cmake_install_test ]
-  dynamic-clang10:
-    description: Build and run tests on clang 10 and AVX 2 with a cmake dynamic build
-    executor: clang10
-    environment: { CMAKE_FLAGS: -DBUILD_SHARED_LIBS=ON }
-    steps: [ cmake_test, cmake_install_test ]
-
-  # unthreaded
-  unthreaded-gcc10:
-    description: Build and run tests on GCC 10 and AVX 2 *without* threads
-    executor: gcc10
-    environment: { CMAKE_FLAGS: -DSIMDJSON_ENABLE_THREADS=OFF }
-    steps: [ cmake_test, cmake_install_test ]
-  unthreaded-clang10:
-    description: Build and run tests on Clang 10 and AVX 2 *without* threads
-    executor: clang10
-    environment: { CMAKE_FLAGS: -DSIMDJSON_ENABLE_THREADS=OFF }
-    steps: [ cmake_test, cmake_install_test ]
-
-  # noexcept
-  noexcept-gcc10:
-    description: Build and run tests on GCC 10 and AVX 2 with exceptions off
-    executor: gcc10
-    environment: { CMAKE_FLAGS: -DSIMDJSON_EXCEPTIONS=OFF }
-    steps: [ cmake_test, cmake_install_test ]
-  noexcept-clang10:
-    description: Build and run tests on Clang 10 and AVX 2 with exceptions off
-    executor: clang10
-    environment: { CMAKE_FLAGS: -DSIMDJSON_EXCEPTIONS=OFF }
-    steps: [ cmake_test, cmake_install_test ]
-
-  #
-  # Misc.
-  #
-
-  # make (test and checkperf)
-  arch-haswell-gcc10:
-    description: Build, run tests and check performance on GCC 10 with -march=haswell
-    executor: gcc10
-    environment: { CXXFLAGS: -march=haswell }
-    steps: [ cmake_test ]
-  arch-nehalem-gcc10:
-    description: Build, run tests and check performance on GCC 10 with -march=nehalem
-    executor: gcc10
-    environment: { CXXFLAGS: -march=nehalem }
-    steps: [ cmake_test ]
-  sanitize-haswell-gcc10:
-    description: Build and run tests on GCC 10 and AVX 2 with a cmake sanitize build
-    executor: gcc10
-    environment: {  CXXFLAGS: -march=haswell, CMAKE_FLAGS: -DCMAKE_BUILD_TYPE=Debug -DBUILD_SHARED_LIBS=ON -DSIMDJSON_SANITIZE=ON, CTEST_FLAGS: --output-on-failure -LE explicitonly }
-    steps: [ cmake_test ]
-  sanitize-haswell-clang10:
-    description: Build and run tests on clang 10 and AVX 2 with a cmake sanitize build
-    executor: clang10
-    environment: { CXXFLAGS: -march=haswell, CMAKE_FLAGS: -DBUILD_SHARED_LIBS=ON  -DSIMDJSON_NO_FORCE_INLINING=ON -DSIMDJSON_SANITIZE=ON, CTEST_FLAGS: --output-on-failure -LE explicitonly }
-    steps: [ cmake_test ]
-
-workflows:
-  version: 2.1
-  build_and_test:
-    jobs:
-      # full multi-implementation tests
-      #- gcc7 tested on GitHub actions
-      - gcc10 # do not delete this as it tests our performance
-      - clang6
-      #- clang10 # this gets tested a lot below
-
-      # libc++
-      - libcpp-clang10
-
-      # full single-implementation tests
-      - sanitize-gcc10
-      - sanitize-clang10
-      - threadsanitize-gcc10
-      - threadsanitize-clang10
-      - dynamic-gcc10
-      - dynamic-clang10
-      - unthreaded-gcc10
-      - unthreaded-clang10
-
-      # no exceptions
-      - noexcept-gcc10
-      - noexcept-clang10
-
-      # quicker make single-implementation tests
-      - arch-haswell-gcc10
-      - arch-nehalem-gcc10
-
-
-      # sanitized single-implementation tests
-      - sanitize-haswell-gcc10
-      - sanitize-haswell-clang10
-
-      # testing "just the library"
-      - justlib-gcc10
-
-      # testing asserts
-      - assert-gcc10
-      - assert-clang10
-
-      # TODO add windows: https://circleci.com/docs/2.0/configuration-reference/#windows

.clangd

@@ -25,6 +25,7 @@ CompileFlags:
 Diagnostics:
     Suppress:
         - pp_including_mainfile_in_preamble
+        - unused-includes
 ---
 # Amalgamated files that require or partly define an implementation
 If:

.github/ISSUE_TEMPLATE/bug_report.md

@@ -9,7 +9,8 @@ assignees: ''
 
 Before submitting an issue, please ensure that you have read the documentation:
 
-* Basics is an overview of how to use simdjson and its APIs: https://github.com/simdjson/simdjson/blob/master/doc/basics.md
+* Basics is an overview of how to use simdjson and its APIs to parse JSON: https://github.com/simdjson/simdjson/blob/master/doc/basics.md
+* Builder is an overview of how to use simdjson to generate JSON: https://github.com/simdjson/simdjson/blob/master/doc/builder.md
 * Performance shows some more advanced scenarios and how to tune for them: https://github.com/simdjson/simdjson/blob/master/doc/performance.md
 * Contributing: https://github.com/simdjson/simdjson/blob/master/CONTRIBUTING.md
 * We follow the [JSON specification as described by RFC 8259](https://www.rfc-editor.org/rfc/rfc8259.txt) (T. Bray, 2017). If you wish to support features that are not part of RFC 8259, then you should not refer to your issue as a bug.
@@ -37,7 +38,7 @@ If we cannot reproduce the issue, then we cannot address it. Note that a stack t
 
 It should be possible to trigger the bug by using solely simdjson with our default build setup. If you can only observe the bug within some specific context, with some other software, please reduce the issue first.
 
-**simjson release**
+**simdjson release**
 
 Unless you plan to contribute to simdjson, you should only work from releases. Please be mindful that our main branch may have additional features, bugs and documentation items.
 
@@ -55,6 +56,8 @@ We support up-to-date 64-bit ARM and x64 FreeBSD, macOS, Windows and Linux syste
 pre-release version of a compiler, do not report it as a bug to simdjson. However, we always
 invite contributions either in the form an analysis or of a code contribution.
 
+Under Windows, we support Visual Studio (both with LLVM and without). We do not support MinGW and other alternate compiler systems. Windows users should be aware that there [is a long-running bug with GCC under Windows](https://gcc.gnu.org/bugzilla/show_bug.cgi?id=54412).
+
 **Indicate whether you are willing or able to provide a bug fix as a pull request**
 
 If you plan to contribute to simdjson, please read our guide:

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: false

.github/ISSUE_TEMPLATE/feature_request.md

@@ -9,7 +9,8 @@ assignees: ''
 
 Before submitting an issue, please ensure that you have read the documentation:
 
-* Basics is an overview of how to use simdjson and its APIs: https://github.com/simdjson/simdjson/blob/master/doc/basics.md
+* Basics is an overview of how to use simdjson and its APIs to parse JSON: https://github.com/simdjson/simdjson/blob/master/doc/basics.md
+* Builder is an overview of how to use simdjson to generate JSON: https://github.com/simdjson/simdjson/blob/master/doc/builder.md
 * Performance shows some more advanced scenarios and how to tune for them: https://github.com/simdjson/simdjson/blob/master/doc/performance.md
 * Contributing: https://github.com/simdjson/simdjson/blob/master/CONTRIBUTING.md
 * We follow the [JSON specification as described by RFC 8259](https://www.rfc-editor.org/rfc/rfc8259.txt) (T. Bray, 2017).

.github/ISSUE_TEMPLATE/standard-issue-template.md

@@ -9,7 +9,8 @@ assignees: ''
 
 Before submitting an issue, please ensure that you have read the documentation:
 
-* Basics is an overview of how to use simdjson and its APIs: https://github.com/simdjson/simdjson/blob/master/doc/basics.md
+* Basics is an overview of how to use simdjson and its APIs to parse JSON: https://github.com/simdjson/simdjson/blob/master/doc/basics.md
+* Builder is an overview of how to use simdjson to generate JSON: https://github.com/simdjson/simdjson/blob/master/doc/builder.md
 * Performance shows some more advanced scenarios and how to tune for them: https://github.com/simdjson/simdjson/blob/master/doc/performance.md
 * Contributing: https://github.com/simdjson/simdjson/blob/master/CONTRIBUTING.md
 * We follow the [JSON specification as described by RFC 8259](https://www.rfc-editor.org/rfc/rfc8259.txt) (T. Bray, 2017).
@@ -18,7 +19,7 @@ We do not make changes to simdjson without clearly identifiable benefits, which
 
 Is your issue:
 
-1. A bug report? If so, please point at a reproducible test. Indicate whether you are willing or able to provide a bug fix as a pull request.
+1. A bug report? If so, please point at a reproducible test. Indicate whether you are willing or able to provide a bug fix as a pull request. As a matter of policy, we do not consider a compiler warning to be a bug.
 
 2. A build issue? If so, provide all possible details regarding your system configuration. If we cannot reproduce your issue, we cannot fix it.
 

.github/pull_request_template.md

@@ -1,8 +1,53 @@
+Short title (summary):
+
+Description
+- What did you change and why? (1-3 sentences)
+- Issue reproduced / related issue: link the issue if relevant (e.g. #123)
+
+Type of change
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Refactor / cleanup
+- [ ] Documentation / tests
+- [ ] Other (please describe):
+
+How to verify / test
+- Add additional tests to verify bugs or new features.
+- If you claim performance gains, you should provide benchmark numbers using high quality benchmarking code.
 
 
-Our tests check whether you have introduced trailing white space. If such a test fails, please check the "artifacts button" above, which if you click it gives a link to a downloadable file to help you identify the issue. You can also run scripts/remove_trailing_whitespace.sh locally if you have a bash shell and the sed command available on your system.
+Please read before contributing:
+- CONTRIBUTING: https://github.com/simdjson/simdjson/blob/master/CONTRIBUTING.md
+- HACKING: https://github.com/simdjson/simdjson/blob/master/HACKING.md
 
-If you plan to contribute to simdjson, please read our
 
-CONTRIBUTING guide: https://github.com/simdjson/simdjson/blob/master/CONTRIBUTING.md and our
-HACKING guide: https://github.com/simdjson/simdjson/blob/master/HACKING.md
+
+If you can, we recommend running our tests with the sanitizers turned on.
+For non-Visual Studio users, it is as easy as doing:
+
+
+
+```bash
+cmake -B build -D SIMDJSON_SANITIZE=ON -D SIMDJSON_DEVELOPER_MODE=ON
+cmake --build build
+ctest --test-dir build
+```
+
+
+Our CI checks, among other things, for trailing whitespace. If a test fails for that reason,
+use the "artifacts" button to download the artifact and inspect the problematic lines,
+or run `scripts/remove_trailing_whitespace.sh` locally if you have a bash shell and `sed`.
+
+
+Checklist before submitting
+- [ ] I added/updated tests covering my change (if applicable)
+- [ ] Code builds locally and passes my check
+- [ ] Documentation / README updated if needed
+- [ ] Commits are atomic and messages are clear
+- [ ] I linked the related issue (if applicable)
+
+Final notes
+- For large PRs, prefer smaller incremental PRs or request staged review.
+
+Thanks for the contribution!
+

.github/workflows/aarch64.yml

@@ -0,0 +1,29 @@
+name: Ubuntu aarch64 (GCC 13)
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+      - master
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: uraimo/run-on-arch-action@v3
+        name: Test
+        id: runcmd
+        with:
+          arch: aarch64
+          distro: ubuntu_latest
+          githubToken: ${{ github.token }}
+          install: |
+            apt-get update -q -y
+            apt-get install -y cmake make g++
+          run: |
+            cmake -DSIMDJSON_SANITIZE_UNDEFINED=ON -DSIMDJSON_DEVELOPER_MODE=ON -DSIMDJSON_COMPETITION=OFF -B build
+            cmake --build build -j=2
+            ctest --output-on-failure --test-dir build

.github/workflows/cifuzz.yml

@@ -17,7 +17,7 @@ jobs:
         fuzz-seconds: 600
         dry-run: false
     - name: Upload Crash
-      uses: actions/upload-artifact@v1
+      uses: actions/upload-artifact@v4
       if: failure() && steps.build.outcome == 'success'
       with:
         name: artifacts

.github/workflows/documentation.yml

@@ -1,9 +1,14 @@
 name: Doxygen GitHub Pages
 
 on:
+  release:
+    # Trigger when a release object is created and when it's published.
+    # Some GitHub flows create a release object then publish it later; include both.
+    types: [created, published]
+  # Also trigger on tag creation pushes so releasing via Git tags still runs the workflow
   push:
-    branches:
-      - master
+    tags:
+      - "v*"  # common release tag pattern like v1.2.3
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 
@@ -28,7 +33,7 @@ jobs:
       - name: Generate Doxygen Documentation
         run: doxygen
       - name: Deploy to GitHub Pages
-        uses: peaceiris/actions-gh-pages@v3
+        uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: doc/api/html

.github/workflows/emscripten.yml

@@ -0,0 +1,17 @@
+on: [push, pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+      - uses: mymindstorm/setup-emsdk@6ab9eb1bda2574c4ddb79809fc9247783eaf9021 # v14
+      - name: Verify
+        run: emcc -v
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v3.6.0
+      - name: Configure
+        run: emcmake cmake -B build
+      - name: Build # We build but do not test
+        run: cmake --build build

.github/workflows/fix-trailing-whitespace.yml

@@ -4,7 +4,7 @@ on: [push, pull_request]
 
 jobs:
   whitespace:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-24.04
     steps:
       - uses: actions/checkout@v4
       - name: Remove whitespace and check the diff
@@ -24,7 +24,7 @@ jobs:
              echo "no trailing whitespace found, good!"
           fi
       - name: Archive whitespace patch
-        uses: actions/upload-artifact@v2
+        uses: actions/upload-artifact@v4
         if: always()
         with:
           name: whitespace-patch

.github/workflows/fuzzers.yml

@@ -24,7 +24,7 @@ jobs:
       implementations: haswell westmere fallback
       UBSAN_OPTIONS: halt_on_error=1
       MAXLEN: -max_len=4000
-      CLANGVERSION: 15
+      CLANGVERSION: 19
       # which optimization level to use for the sanitizer build (see build_fuzzer.variants.sh)
       OPTLEVEL: -O3
 
@@ -125,7 +125,7 @@ jobs:
         done
 
     - name: Save the corpus as a github artifact
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       with:
         name: corpus
         path: corpus.tar
@@ -148,7 +148,7 @@ jobs:
       run: tar cf valgrind.tar valgrind-*.txt
 
     - name: Save valgrind output as a github artifact
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       if: always()
       with:
         name: valgrindresults
@@ -156,7 +156,7 @@ jobs:
         if-no-files-found: ignore
 
     - name: Archive any crashes as an artifact
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       if: always()
       with:
         name: crashes

.github/workflows/msys2-clang.yml

@@ -20,7 +20,7 @@ jobs:
           - msystem: "MINGW64"
             install: mingw-w64-x86_64-libxml2 mingw-w64-x86_64-cmake mingw-w64-x86_64-ninja mingw-w64-x86_64-clang
             type: Debug
-            - msystem: "MINGW64"
+          - msystem: "MINGW64"
             install: mingw-w64-x86_64-libxml2 mingw-w64-x86_64-cmake mingw-w64-x86_64-ninja mingw-w64-x86_64-clang
             type: RelWithDebInfo
     env:

.github/workflows/msys2.yml

@@ -22,7 +22,7 @@ jobs:
           - msystem: "MINGW64"
             install: mingw-w64-x86_64-cmake mingw-w64-x86_64-ninja mingw-w64-x86_64-gcc
             type: Debug
-            - msystem: "MINGW64"
+          - msystem: "MINGW64"
             install: mingw-w64-x86_64-cmake mingw-w64-x86_64-ninja mingw-w64-x86_64-gcc
             type: RelWithDebInfo
     env:

.github/workflows/ppc64.yml

@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: uraimo/run-on-arch-action@v2
+      - uses: uraimo/run-on-arch-action@v3
         name: Test
         id: runcmd
         with:
@@ -24,6 +24,6 @@ jobs:
             apt-get update -q -y
             apt-get install -y cmake make g++
           run: |
-            cmake -DCMAKE_BUILD_TYPE=Release -B build
+            cmake -DCMAKE_BUILD_TYPE=Release -DSIMDJSON_DEVELOPER_MODE=ON -DSIMDJSON_COMPETITION=OFF  -B build
             cmake --build build -j=2
             ctest --output-on-failure --test-dir build

.github/workflows/riscv64.yml

@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: uraimo/run-on-arch-action@v2
+      - uses: uraimo/run-on-arch-action@v3
         name: Test
         id: runcmd
         with:
@@ -24,6 +24,6 @@ jobs:
             apt-get update -q -y
             apt-get install -y cmake make g++
           run: |
-            cmake -DCMAKE_BUILD_TYPE=Release -B build
+            cmake -DCMAKE_BUILD_TYPE=Release -DSIMDJSON_DEVELOPER_MODE=ON -DSIMDJSON_COMPETITION=OFF  -B build
             cmake --build build -j=2
             ctest --output-on-failure --test-dir build

.github/workflows/rvv-1024-clang-18.yml

@@ -0,0 +1,29 @@
+name: Ubuntu rvv VLEN=1024 (clang 18)
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+      - master
+
+jobs:
+  build:
+    runs-on: ubuntu-24.04
+    steps:
+    - uses: actions/checkout@v4
+    - name: Install packages
+      run: |
+        sudo apt-get update -q -y
+        sudo apt-get install -y cmake make g++-riscv64-linux-gnu qemu-user-static clang-18
+    - name: Build
+      run: |
+        CXX=clang++-18 CXXFLAGS="--target=riscv64-linux-gnu -march=rv64gcv_zvbb" \
+        cmake --toolchain=cmake/toolchains-ci/riscv64-linux-gnu.cmake -DCMAKE_BUILD_TYPE=Release -B build
+        cmake --build build/ -j$(nproc)
+    - name: Test VLEN=1024
+      run: |
+        export QEMU_LD_PREFIX="/usr/riscv64-linux-gnu"
+        export QEMU_CPU="rv64,v=on,zvbb=on,vlen=1024,rvv_ta_all_1s=on,rvv_ma_all_1s=on"
+        ctest --timeout 1800 --output-on-failure --test-dir build -j $(nproc)

.github/workflows/rvv-128-clang-17.yml

@@ -0,0 +1,29 @@
+name: Ubuntu rvv VLEN=128 (clang 17)
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+      - master
+
+jobs:
+  build:
+    runs-on: ubuntu-24.04
+    steps:
+    - uses: actions/checkout@v4
+    - name: Install packages
+      run: |
+        sudo apt-get update -q -y
+        sudo apt-get install -y cmake make g++-riscv64-linux-gnu qemu-user-static clang-17
+    - name: Build
+      run: |
+        CXX=clang++-17 CXXFLAGS="--target=riscv64-linux-gnu -march=rv64gcv" \
+        cmake --toolchain=cmake/toolchains-ci/riscv64-linux-gnu.cmake -DCMAKE_BUILD_TYPE=Release -B build
+        cmake --build build/ -j$(nproc)
+    - name: Test VLEN=128
+      run: |
+        export QEMU_LD_PREFIX="/usr/riscv64-linux-gnu"
+        export QEMU_CPU="rv64,v=on,vlen=128,rvv_ta_all_1s=on,rvv_ma_all_1s=on"
+        ctest --timeout 1800 --output-on-failure --test-dir build -j $(nproc)

.github/workflows/rvv-256-gcc-14.yml

@@ -0,0 +1,29 @@
+name: Ubuntu rvv VLEN=256 (gcc 14)
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+      - master
+
+jobs:
+  build:
+    runs-on: ubuntu-24.04
+    steps:
+    - uses: actions/checkout@v4
+    - name: Install packages
+      run: |
+        sudo apt-get update -q -y
+        sudo apt-get install -y cmake make g++-14-riscv64-linux-gnu qemu-user-static
+    - name: Build
+      run: |
+        CXX=riscv64-linux-gnu-g++-14 CXXFLAGS=-march=rv64gcv \
+        cmake --toolchain=cmake/toolchains-ci/riscv64-linux-gnu.cmake -DCMAKE_BUILD_TYPE=Release -B build
+        cmake --build build/ -j$(nproc)
+    - name: Test VLEN=256
+      run: |
+        export QEMU_LD_PREFIX="/usr/riscv64-linux-gnu"
+        export QEMU_CPU="rv64,v=on,zvbb=on,vlen=256,rvv_ta_all_1s=on,rvv_ma_all_1s=on"
+        ctest --timeout 1800 --output-on-failure --test-dir build -j $(nproc)

.github/workflows/s390x.yml

@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: uraimo/run-on-arch-action@v2
+      - uses: uraimo/run-on-arch-action@v3
         name: Test
         id: runcmd
         with:
@@ -24,6 +24,6 @@ jobs:
             apt-get update -q -y
             apt-get install -y cmake make g++
           run: |
-            cmake -DCMAKE_BUILD_TYPE=Release -B build
+            cmake -DCMAKE_BUILD_TYPE=Release  -DSIMDJSON_DEVELOPER_MODE=ON -DSIMDJSON_COMPETITION=OFF -B build
             cmake --build build -j=2
             ctest --output-on-failure --test-dir build

.github/workflows/ubuntu20-gcc8.yml

@@ -1,38 +0,0 @@
-name: Ubuntu 20.04 CI (GCC 8)
-
-on: [push, pull_request]
-
-jobs:
-  ubuntu-build:
-    if: >-
-      ! contains(toJSON(github.event.commits.*.message), '[skip ci]') &&
-      ! contains(toJSON(github.event.commits.*.message), '[skip github]')
-    runs-on: ubuntu-20.04
-    env:
-      CXX: g++-8
-      CC: gcc-8
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/cache@v4
-        with:
-          path: dependencies/.cache
-          key: ${{ hashFiles('dependencies/CMakeLists.txt') }}
-      - name: Install GCC 8
-        run: sudo apt-get install -y g++-8
-      - name: Use cmake
-        run: |
-          mkdir builddebug &&
-          cd builddebug &&
-          cmake -DCMAKE_BUILD_TYPE=Debug -DSIMDJSON_GOOGLE_BENCHMARKS=OFF -DSIMDJSON_DEVELOPER_MODE=ON -DBUILD_SHARED_LIBS=OFF ..  &&
-          cmake --build .   &&
-          ctest --output-on-failure -LE explicitonly -j   &&
-          cd .. &&
-          mkdir build &&
-          cd build &&
-          cmake  -DSIMDJSON_GOOGLE_BENCHMARKS=ON -DSIMDJSON_DEVELOPER_MODE=ON -DBUILD_SHARED_LIBS=OFF -DCMAKE_INSTALL_PREFIX:PATH=destination ..  &&
-          cmake --build .   &&
-          ctest --output-on-failure -LE explicitonly -j   &&
-          cmake --install . &&
-          echo -e '#include <simdjson.h>\nint main(int argc,char**argv) {simdjson::dom::parser parser;simdjson::dom::element tweets = parser.load(argv[1]); }' > tmp.cpp && c++ -Idestination/include -Ldestination/lib -std=c++17 -Wl,-rpath,destination/lib -o linkandrun tmp.cpp -lsimdjson && ./linkandrun jsonexamples/twitter.json &&
-          cd ../tests/installation_tests/find &&
-          mkdir build && cd build && cmake -DCMAKE_INSTALL_PREFIX:PATH=../../../build/destination .. &&  cmake --build .

.github/workflows/ubuntu20.yml

@@ -1,47 +0,0 @@
-name: Ubuntu 20.04 CI (GCC 9)
-
-on: [push, pull_request]
-
-jobs:
-  ubuntu-build:
-    if: >-
-      ! contains(toJSON(github.event.commits.*.message), '[skip ci]') &&
-      ! contains(toJSON(github.event.commits.*.message), '[skip github]')
-    runs-on: ubuntu-20.04
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/cache@v4
-        with:
-          path: dependencies/.cache
-          key: ${{ hashFiles('dependencies/CMakeLists.txt') }}
-      - name: Use cmake to build just the library
-        run: |
-          mkdir buildjustlib &&
-          cd buildjustlib &&
-          cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=OFF -DSIMDJSON_DEVELOPER_MODE=OFF -DCMAKE_INSTALL_PREFIX:PATH=destination ..  &&
-          cmake --build .   &&
-          cmake --install . &&
-          echo -e '#include <simdjson.h>\nint main(int argc,char**argv) {simdjson::dom::parser parser;simdjson::dom::element tweets = parser.load(argv[1]); }' > tmp.cpp &&
-          c++ -Idestination/include -Ldestination/lib -std=c++17 -Wl,-rpath,destination/lib -o linkandrun tmp.cpp -lsimdjson &&
-          cd ../tests/installation_tests/find &&
-          mkdir buildjustlib &&
-          cd buildjustlib &&
-          cmake -DCMAKE_INSTALL_PREFIX:PATH=../../../buildjustlib/destination .. &&
-          cmake --build .
-      - name: Use cmake
-        run: |
-          mkdir builddebug &&
-          cd builddebug &&
-          cmake -DCMAKE_BUILD_TYPE=Debug -DSIMDJSON_GOOGLE_BENCHMARKS=OFF -DSIMDJSON_DEVELOPER_MODE=ON -DBUILD_SHARED_LIBS=OFF ..  &&
-          cmake --build .   &&
-          ctest --output-on-failure -LE explicitonly -j   &&
-          cd .. &&
-          mkdir build &&
-          cd build &&
-          cmake  -DSIMDJSON_GOOGLE_BENCHMARKS=ON -DSIMDJSON_DEVELOPER_MODE=ON -DBUILD_SHARED_LIBS=OFF -DCMAKE_INSTALL_PREFIX:PATH=destination ..  &&
-          cmake --build .   &&
-          ctest --output-on-failure -LE explicitonly -j   &&
-          cmake --install . &&
-          echo -e '#include <simdjson.h>\nint main(int argc,char**argv) {simdjson::dom::parser parser;simdjson::dom::element tweets = parser.load(argv[1]); }' > tmp.cpp && c++ -Idestination/include -Ldestination/lib -std=c++17 -Wl,-rpath,destination/lib -o linkandrun tmp.cpp -lsimdjson && ./linkandrun jsonexamples/twitter.json &&
-          cd ../tests/installation_tests/find &&
-          mkdir build && cd build && cmake -DCMAKE_INSTALL_PREFIX:PATH=../../../build/destination .. &&  cmake --build .

.github/workflows/ubuntu22-cxx20.yml

@@ -14,20 +14,52 @@ jobs:
         with:
           path: dependencies/.cache
           key: ${{ hashFiles('dependencies/CMakeLists.txt') }}
-      - name: Use cmake
+
+      - name: Configure Debug Build
         run: |
-          mkdir builddebug &&
-          cd builddebug &&
-          CXX=g++-12 cmake -DSIMDJSON_CXX_STANDARD=20 -DCMAKE_BUILD_TYPE=Debug -DSIMDJSON_GOOGLE_BENCHMARKS=OFF -DSIMDJSON_DEVELOPER_MODE=ON -DBUILD_SHARED_LIBS=OFF ..  &&
-          cmake --build .   &&
-          ctest --output-on-failure -LE explicitonly -j   &&
-          cd .. &&
-          mkdir build &&
-          cd build &&
-          CXX=g++-12 cmake -DSIMDJSON_CXX_STANDARD=20  -DSIMDJSON_GOOGLE_BENCHMARKS=ON -DSIMDJSON_DEVELOPER_MODE=ON -DBUILD_SHARED_LIBS=OFF -DCMAKE_INSTALL_PREFIX:PATH=destination ..  &&
-          cmake --build .   &&
-          ctest --output-on-failure -LE explicitonly -j   &&
-          cmake --install . &&
-          echo -e '#include <simdjson.h>\nint main(int argc,char**argv) {simdjson::dom::parser parser;simdjson::dom::element tweets = parser.load(argv[1]); }' > tmp.cpp && c++ -Idestination/include -Ldestination/lib -std=c++17 -Wl,-rpath,destination/lib -o linkandrun tmp.cpp -lsimdjson && ./linkandrun jsonexamples/twitter.json &&
-          cd ../tests/installation_tests/find &&
-          mkdir build && cd build && cmake -DCMAKE_INSTALL_PREFIX:PATH=../../../build/destination .. &&  cmake --build .
+          CXX=g++-12 cmake -DSIMDJSON_CXX_STANDARD=20 -DCMAKE_BUILD_TYPE=Debug -DSIMDJSON_GOOGLE_BENCHMARKS=OFF -DSIMDJSON_DEVELOPER_MODE=ON -DBUILD_SHARED_LIBS=OFF -B builddebug
+
+      - name: Compile Debug Build
+        run: |
+          cmake --build builddebug
+
+      - name: Test Debug Build
+        run: |
+          ctest --output-on-failure -LE explicitonly -j --test-dir builddebug
+
+      - name: Configure Release Build
+        run: |
+          CXX=g++-12 cmake -DSIMDJSON_CXX_STANDARD=20 -DSIMDJSON_GOOGLE_BENCHMARKS=ON -DSIMDJSON_DEVELOPER_MODE=ON -DBUILD_SHARED_LIBS=OFF -DCMAKE_INSTALL_PREFIX:PATH=destination -B build
+
+      - name: Compile Release Build
+        run: |
+          cmake --build build
+
+      - name: Test Release Build
+        run: |
+          ctest --output-on-failure -LE explicitonly -j --test-dir build
+
+      - name: Install Release Build
+        run: |
+          cmake --install build
+
+      - name: Generate Example Code
+        run: |
+          echo -e '#include <simdjson.h>\nint main(int argc,char**argv) {simdjson::dom::parser parser;simdjson::dom::element tweets = parser.load(argv[1]); }' > tmp.cpp
+
+      - name: Compile Example Code
+        run: |
+          c++ -Idestination/include -Ldestination/lib -std=c++17 -Wl,-rpath,destination/lib -o linkandrun tmp.cpp -lsimdjson
+
+      - name: Run Example Code
+        run: |
+          ./linkandrun jsonexamples/twitter.json
+
+      - name: Configure Find Tests
+        run: |
+          cd tests/installation_tests/find && \
+          cmake -DCMAKE_INSTALL_PREFIX:PATH=../../../destination -B build
+
+      - name: Compile Find Tests
+        run: |
+          cd tests/installation_tests/find && cmake --build build

.github/workflows/ubuntu24-checkperf.yml

@@ -13,7 +13,7 @@ jobs:
     if: >-
       ! contains(toJSON(github.event.commits.*.message), '[skip ci]') &&
       ! contains(toJSON(github.event.commits.*.message), '[skip github]')
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-24.04
     steps:
       - uses: actions/checkout@v4
       - uses: actions/cache@v4

.github/workflows/ubuntu24-cxx20-noexcept.yml

@@ -0,0 +1,22 @@
+name: Ubuntu 24.04 CI (CXX 20, noexcept)
+
+on: [push, pull_request]
+jobs:
+  ubuntu-build:
+    if: >-
+      ! contains(toJSON(github.event.commits.*.message), '[skip ci]') &&
+      ! contains(toJSON(github.event.commits.*.message), '[skip github]')
+    runs-on: ubuntu-24.04
+    strategy:
+      matrix:
+        cxx: [g++-13, clang++-16]
+    steps:
+      - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
+      - name: Prepare
+        run: cmake -DSIMDJSON_CXX_STANDARD=20 -DSIMDJSON_EXCEPTIONS=OFF -DSIMDJSON_DEVELOPER_MODE=ON  -B build
+        env:
+          CXX: ${{matrix.cxx}}
+      - name: Build
+        run: cmake --build build -j=2
+      - name: Test
+        run: ctest --output-on-failure --test-dir build

.github/workflows/ubuntu24-cxx20.yml

@@ -0,0 +1,22 @@
+name: Ubuntu 24.04 CI (CXX 20)
+
+on: [push, pull_request]
+jobs:
+  ubuntu-build:
+    if: >-
+      ! contains(toJSON(github.event.commits.*.message), '[skip ci]') &&
+      ! contains(toJSON(github.event.commits.*.message), '[skip github]')
+    runs-on: ubuntu-24.04
+    strategy:
+      matrix:
+        cxx: [g++-13, clang++-16]
+    steps:
+      - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
+      - name: Prepare
+        run: cmake -DSIMDJSON_CXX_STANDARD=20 -DSIMDJSON_DEVELOPER_MODE=ON  -B build
+        env:
+          CXX: ${{matrix.cxx}}
+      - name: Build
+        run: cmake --build build -j=2
+      - name: Test
+        run: ctest --output-on-failure --test-dir build

.github/workflows/ubuntu24-noexcept.yml

@@ -7,7 +7,7 @@ jobs:
     if: >-
       ! contains(toJSON(github.event.commits.*.message), '[skip ci]') &&
       ! contains(toJSON(github.event.commits.*.message), '[skip github]')
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-24.04
     steps:
       - uses: actions/checkout@v4
       - uses: actions/cache@v4
@@ -31,4 +31,4 @@ jobs:
           echo -e '#include <simdjson.h>\nint main(int argc,char**argv) {simdjson::dom::parser parser;simdjson::dom::element tweets = parser.load(argv[1]); }' > tmp.cpp && c++ -Idestination/include -Ldestination/lib -std=c++17 -Wl,-rpath,destination/lib -o linkandrun tmp.cpp -lsimdjson && ./linkandrun jsonexamples/twitter.json &&
           mkdir testfindpackage &&
           cd testfindpackage &&
-          echo -e 'cmake_minimum_required(VERSION 3.1)\nproject(simdjsontester)\nset(CMAKE_CXX_STANDARD 17)\nfind_package(simdjson REQUIRED)'> CMakeLists.txt && mkdir build && cd build && cmake -DCMAKE_INSTALL_PREFIX:PATH=../destination .. &&  cmake --build .
+          echo -e 'cmake_minimum_required(VERSION 3.14)\nproject(simdjsontester)\nset(CMAKE_CXX_STANDARD 17)\nfind_package(simdjson REQUIRED)'> CMakeLists.txt && mkdir build && cd build && cmake -DCMAKE_INSTALL_PREFIX:PATH=../destination .. &&  cmake --build .

.github/workflows/ubuntu24-nothread.yml

@@ -7,7 +7,7 @@ jobs:
     if: >-
       ! contains(toJSON(github.event.commits.*.message), '[skip ci]') &&
       ! contains(toJSON(github.event.commits.*.message), '[skip github]')
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-24.04
     steps:
       - uses: actions/checkout@v4
       - uses: actions/cache@v4
@@ -31,4 +31,4 @@ jobs:
           echo -e '#include <simdjson.h>\nint main(int argc,char**argv) {simdjson::dom::parser parser;simdjson::dom::element tweets = parser.load(argv[1]); }' > tmp.cpp && c++ -Idestination/include -Ldestination/lib -std=c++17 -Wl,-rpath,destination/lib -o linkandrun tmp.cpp -lsimdjson && ./linkandrun jsonexamples/twitter.json &&
           mkdir testfindpackage &&
           cd testfindpackage &&
-          echo -e 'cmake_minimum_required(VERSION 3.1)\nproject(simdjsontester)\nset(CMAKE_CXX_STANDARD 17)\nfind_package(simdjson REQUIRED)'> CMakeLists.txt && mkdir build && cd build && cmake -DCMAKE_INSTALL_PREFIX:PATH=../destination .. &&  cmake --build .
+          echo -e 'cmake_minimum_required(VERSION 3.14)\nproject(simdjsontester)\nset(CMAKE_CXX_STANDARD 17)\nfind_package(simdjson REQUIRED)'> CMakeLists.txt && mkdir build && cd build && cmake -DCMAKE_INSTALL_PREFIX:PATH=../destination .. &&  cmake --build .

.github/workflows/ubuntu24-sani.yml

@@ -7,7 +7,7 @@ jobs:
     if: >-
       ! contains(toJSON(github.event.commits.*.message), '[skip ci]') &&
       ! contains(toJSON(github.event.commits.*.message), '[skip github]')
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-24.04
     steps:
       - uses: actions/checkout@v4
       - uses: actions/cache@v4
@@ -25,7 +25,7 @@ jobs:
     if: >-
       ! contains(toJSON(github.event.commits.*.message), '[skip ci]') &&
       ! contains(toJSON(github.event.commits.*.message), '[skip github]')
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-24.04
     steps:
       - uses: actions/checkout@v4
       - uses: actions/cache@v4

.github/workflows/vs17-arm-ci.yml

@@ -10,7 +10,6 @@ jobs:
        fail-fast: false
        matrix:
          include:
-           - {arch: ARM}
            - {arch: ARM64}
            - {arch: ARM64EC}
      steps:
@@ -19,4 +18,4 @@ jobs:
        - name: Use cmake
          run: |
            cmake -A ${{ matrix.arch }} -DCMAKE_SYSTEM_VERSION="10.0.22621.0" -DCMAKE_CROSSCOMPILING=1 -DSIMDJSON_DEVELOPER_MODE=ON -D SIMDJSON_GOOGLE_BENCHMARKS=OFF -DSIMDJSON_EXCEPTIONS=OFF -B build  &&
-           cmake --build build --verbose
+           cmake --build build --verbose

.github/workflows/vs17-ci-sani.yml

@@ -0,0 +1,30 @@
+name: VS17-CI-SANITIZE
+
+on: [push, pull_request]
+
+jobs:
+  ci:
+    if: >-
+      ! contains(toJSON(github.event.commits.*.message), '[skip ci]') &&
+      ! contains(toJSON(github.event.commits.*.message), '[skip github]')
+    name: windows-vs17
+    runs-on: windows-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - {gen: Visual Studio 17 2022, arch: x64, shared: OFF, build_type: Debug}
+          - {gen: Visual Studio 17 2022, arch: x64, shared: OFF, build_type: Release}
+          - {gen: Visual Studio 17 2022, arch: x64, shared: OFF, build_type: RelWithDebInfo}
+    steps:
+    - name: checkout
+      uses: actions/checkout@v4
+    - name: Configure
+      run: |
+        cmake -G "${{matrix.gen}}" -A ${{matrix.arch}} -DSANITIZE=ON -DSIMDJSON_DEVELOPER_MODE=ON -DSIMDJSON_COMPETITION=OFF -DBUILD_SHARED_LIBS=${{matrix.shared}} -B build
+    - name: Build
+      run: cmake --build build --config ${{matrix.build_type}} --verbose
+    - name: Run tests
+      run: |
+        cd build
+        ctest -C ${{matrix.build_type}}  -LE explicitonly  --output-on-failure

.github/workflows/vs17-ci.yml

@@ -26,15 +26,15 @@ jobs:
       run: |
         cmake -G "${{matrix.gen}}" -A ${{matrix.arch}} -DSIMDJSON_DEVELOPER_MODE=ON -DSIMDJSON_COMPETITION=OFF -DBUILD_SHARED_LIBS=${{matrix.shared}} -B build
     - name: Build Debug
-      run: cmake --build build --config ${{build_type}} --verbose
+      run: cmake --build build --config ${{matrix.build_type}} --verbose
     - name: Run tests
       run: |
         cd build
-        ctest -C ${{build_type}}  -LE explicitonly  --output-on-failure
+        ctest -C ${{matrix.build_type}}  -LE explicitonly  --output-on-failure
     - name: Install
       run: |
-        cmake --install build --config ${{build_type}}
+        cmake --install build --config ${{matrix.build_type}}
     - name: Test Installation
       run: |
         cmake -G "${{matrix.gen}}" -A ${{matrix.arch}}  -B build_install_test tests/installation_tests/find
-        cmake --build build_install_test --config ${{build_type}}
+        cmake --build build_install_test --config ${{matrix.build_type}}

.github/workflows/vs17-clang-ci-cxx20.yml

@@ -0,0 +1,37 @@
+name: VS17-CLANG-CI
+
+on: [push, pull_request]
+
+jobs:
+  ci:
+    if: >-
+      ! contains(toJSON(github.event.commits.*.message), '[skip ci]') &&
+      ! contains(toJSON(github.event.commits.*.message), '[skip github]')
+    name: windows-vs17
+    runs-on: windows-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - {gen: Visual Studio 17 2022, arch: x64, build_type: Debug}
+          - {gen: Visual Studio 17 2022, arch: x64, build_type: Release}
+          - {gen: Visual Studio 17 2022, arch: x64, build_type: RelWithDebInfo}
+    steps:
+    - name: checkout
+      uses: actions/checkout@v4
+    - name: Configure
+      run: |
+        cmake -G "${{matrix.gen}}" -A ${{matrix.arch}}  -T ClangCL -DSIMDJSON_DEVELOPER_MODE=ON -DSIMDJSON_COMPETITION=OFF -B build
+    - name: Build
+      run: cmake --build build --config ${{matrix.build_type}} --verbose
+    - name: Run tests
+      run: |
+        cd build
+        ctest -C ${{matrix.build_type}}  -LE explicitonly  --output-on-failure
+    - name: Install
+      run: |
+        cmake --install build --config ${{matrix.build_type}}
+    - name: Test Installation
+      run: |
+        cmake -G "${{matrix.gen}}" -A ${{matrix.arch}}  -B build_install_test tests/installation_tests/find
+        cmake --build build_install_test --config ${{matrix.build_type}}

.gitignore

@@ -38,7 +38,7 @@ cmake-build-release/
 .history/
 
 # Visual Studio artifacts
-/VS/
+/.vs/
 
 # C/C++ build outputs
 .build/
@@ -106,4 +106,4 @@ objs
 !.vscode/extensions.json
 
 # clangd
-.cache
+.cache

.vscode/settings.json

@@ -3,6 +3,9 @@
         {"column": 95 },
         {"column": 120 }
     ],
+    "cmake.configureArgs": [
+        "-DSIMDJSON_DEVELOPER_MODE=ON"
+    ],
     "files.trimTrailingWhitespace": true,
     "files.associations": {
         ".clangd": "yaml",
@@ -109,6 +112,23 @@
         "numbers": "cpp",
         "semaphore": "cpp",
         "stop_token": "cpp",
-        "cfenv": "cpp"
+        "cfenv": "cpp",
+        "format": "cpp",
+        "xlocmes": "cpp",
+        "xlocmon": "cpp",
+        "xlocnum": "cpp",
+        "xloctime": "cpp",
+        "xutility": "cpp",
+        "coroutine": "cpp",
+        "xfacet": "cpp",
+        "xhash": "cpp",
+        "xiosbase": "cpp",
+        "xlocale": "cpp",
+        "xlocbuf": "cpp",
+        "xlocinfo": "cpp",
+        "xmemory": "cpp",
+        "xstring": "cpp",
+        "xtr1common": "cpp",
+        "xtree": "cpp"
     }
 }

CMakeLists.txt

@@ -3,7 +3,7 @@ cmake_minimum_required(VERSION 3.14)
 project(
     simdjson
     # The version number is modified by tools/release.py
-    VERSION 3.9.4
+    VERSION 4.2.4
     DESCRIPTION "Parsing gigabytes of JSON per second"
     HOMEPAGE_URL "https://simdjson.org/"
     LANGUAGES CXX C
@@ -20,10 +20,14 @@ string(
 # ---- Options, variables ----
 
 # These version numbers are modified by tools/release.py
-set(SIMDJSON_LIB_VERSION "22.0.0" CACHE STRING "simdjson library version")
-set(SIMDJSON_LIB_SOVERSION "22" CACHE STRING "simdjson library soversion")
+set(SIMDJSON_LIB_VERSION "29.0.0" CACHE STRING "simdjson library version")
+set(SIMDJSON_LIB_SOVERSION "29" CACHE STRING "simdjson library soversion")
 
-option(SIMDJSON_BUILD_STATIC_LIB "Build simdjson_static library along with simdjson" OFF)
+option(SIMDJSON_BUILD_STATIC_LIB "Build simdjson_static library along with simdjson (only makes sense if BUILD_SHARED_LIBS=ON)" OFF)
+if(SIMDJSON_BUILD_STATIC_LIB AND NOT BUILD_SHARED_LIBS)
+  message(WARNING "SIMDJSON_BUILD_STATIC_LIB only makes sense if BUILD_SHARED_LIBS is set to ON")
+  message(WARNING "You might be building and installing a two identical static libraries.")
+endif()
 
 option(SIMDJSON_ENABLE_THREADS "Link with thread support" ON)
 
@@ -39,6 +43,20 @@ if(SIMDJSON_DISABLE_DEPRECATED_API)
   )
 endif()
 
+if(${CMAKE_VERSION} VERSION_GREATER_EQUAL "3.25.0")
+    option(SIMDJSON_STATIC_REFLECTION "Enables static reflection (experimental), requires C++26" OFF)
+else()
+    set(SIMDJSON_STATIC_REFLECTION OFF CACHE BOOL "Enables static reflection (experimental)" FORCE)
+    message(WARNING "SIMDJSON_STATIC_REFLECTION is disabled because your CMake version is below 3.25")
+endif()
+
+if(SIMDJSON_STATIC_REFLECTION)
+  simdjson_add_props(
+      target_compile_definitions PUBLIC
+      SIMDJSON_STATIC_REFLECTION=1
+  )
+endif()
+
 option(SIMDJSON_DEVELOPMENT_CHECKS "Enable development-time aids, such as \
 checks for incorrect API usage. Enabled by default in DEBUG." OFF)
 if(SIMDJSON_DEVELOPMENT_CHECKS)
@@ -51,6 +69,7 @@ endif()
 if(is_top_project)
   option(SIMDJSON_DEVELOPER_MODE "Enable targets for developing simdjson" OFF)
   option(BUILD_SHARED_LIBS "Build simdjson as a shared library" OFF)
+  option(SIMDJSON_SINGLEHEADER "Disable singleheader generation" ON)
 endif()
 
 include(cmake/handle-deprecations.cmake)
@@ -79,7 +98,7 @@ set_target_properties(
 )
 
 # FIXME: Use proper CMake integration for exports
-if(MSVC AND BUILD_SHARED_LIBS)
+if(WIN32 AND BUILD_SHARED_LIBS)
   target_compile_definitions(
       simdjson
       PRIVATE SIMDJSON_BUILDING_WINDOWS_DYNAMIC_LIBRARY=1
@@ -93,7 +112,16 @@ simdjson_add_props(
     PRIVATE "$<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}/src>"
 )
 
-simdjson_add_props(target_compile_features PUBLIC cxx_std_11)
+if(SIMDJSON_STATIC_REFLECTION)
+  # We would like to require C++26, but no compiler supports that!
+  # This is a hack:
+  simdjson_add_props(
+      target_compile_options PUBLIC
+      -freflection -fexpansion-statements -stdlib=libc++ -std=c++26
+  )
+else()
+  simdjson_add_props(target_compile_features PUBLIC cxx_std_11)
+endif()
 
 # workaround for GNU GCC poor AVX load/store code generation
 if(
@@ -106,6 +134,12 @@ if(
   )
 endif()
 
+option(SIMDJSON_MINUS_ZERO_AS_FLOAT "Treat -0 as a floating-point value" OFF)
+
+if(SIMDJSON_MINUS_ZERO_AS_FLOAT)
+  simdjson_add_props(target_compile_definitions PRIVATE SIMDJSON_MINUS_ZERO_AS_FLOAT=1)
+endif(SIMDJSON_MINUS_ZERO_AS_FLOAT)
+
 if(CMAKE_SYSTEM_PROCESSOR MATCHES "^(loongarch64)$")
     option(SIMDJSON_PREFER_LSX "Prefer LoongArch SX" ON)
     include(CheckCXXCompilerFlag)
@@ -155,11 +189,13 @@ endif()
 include(CMakePackageConfigHelpers)
 include(GNUInstallDirs)
 
-install(
-    FILES singleheader/simdjson.h
-    DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}"
-    COMPONENT simdjson_Development
-)
+if(SIMDJSON_SINGLEHEADER)
+  install(
+      FILES singleheader/simdjson.h
+      DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}"
+      COMPONENT simdjson_Development
+  )
+endif()
 
 install(
     TARGETS simdjson
@@ -203,6 +239,7 @@ if(SIMDJSON_BUILD_STATIC_LIB)
       TARGETS simdjson_static
       EXPORT simdjson_staticTargets
       ARCHIVE COMPONENT simdjson_Development
+      INCLUDES DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}"
   )
   install(
       EXPORT simdjson_staticTargets
@@ -279,6 +316,7 @@ enable_testing()
 add_custom_target(all_tests)
 
 add_subdirectory(windows)
+include(cmake/CPM.cmake)
 add_subdirectory(dependencies) ## This needs to be before tools because of cxxopts
 add_subdirectory(tools)  ## This needs to be before tests because of cxxopts
 
@@ -286,8 +324,9 @@ add_subdirectory(tools)  ## This needs to be before tests because of cxxopts
 # most of the data has been moved to https://github.com/simdjson/simdjson-data
 add_subdirectory(jsonexamples)
 
-
+if(SIMDJSON_SINGLEHEADER)
 add_subdirectory(singleheader)
+endif()
 
 
 

CONTRIBUTING.md

@@ -92,7 +92,7 @@ We welcome contributions from women and less represented groups. If you need hel
 
 Consider the following points when engaging with the project:
 
-- We discourage arguments from authority: ideas are discusssed on their own merits and not based on who stated it.
+- We discourage arguments from authority: ideas are discussed on their own merits and not based on who stated it.
 - Be mindful that what you may view as an aggression is maybe merely a difference of opinion or a misunderstanding.
 - Be mindful that a collection of small aggressions, even if mild in isolation, can become harmful.
 

Doxyfile

@@ -38,7 +38,7 @@ PROJECT_NAME           = simdjson
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = "3.9.4"
+PROJECT_NUMBER         = "4.2.4"
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a

HACKING.md

@@ -20,13 +20,54 @@ If you plan to contribute to simdjson, please read our [CONTRIBUTING](https://gi
 Build Quickstart
 ------------------------------
 
+For non-Windows system,
+
 ```bash
-mkdir build
-cd build
-cmake -D SIMDJSON_DEVELOPER_MODE=ON ..
-cmake --build .
+cmake -B -D SIMDJSON_DEVELOPER_MODE=ON ..
+cmake --build build
+ctest --test-dir build
 ```
 
+It is similar for Visual Studio users, please see the CMake or Visual Studio documentation.
+
+By default the library is built in Release mode.
+
+
+Assertions and development checks
+------------------------------
+
+We do not use conventional `assert` in simdjson. Instead we use the macro
+`SIMDJSON_ASSUME`:
+
+```cpp
+SIMDJSON_ASSUME(something_that_is_true());
+```
+
+Sometimes, you need to do a bit more work that a simple check.
+The `SIMDJSON_DEVELOPMENT_CHECKS` macro is true only in Debug mode unless manually set.
+It is acceptable to add checks that you would not do in Release mode as long as
+they are guarded:
+
+```cpp
+#if SIMDJSON_DEVELOPMENT_CHECKS
+// do sanity checks here
+```
+
+
+Working with sanitizers
+------------------------------
+
+The simdjson library must be memory-safe. We cannot allow buffer overruns.
+During development, if you system supports it, we recommend configuring
+the project with `-D SIMDJSON_SANITIZE=ON`.
+
+```bash
+cmake -B -D SIMDJSON_SANITIZE=ON -D SIMDJSON_DEVELOPER_MODE=ON ..
+cmake --build build
+ctest --test-dir build
+```
+
+
 Design notes
 ------------------------------
 
@@ -88,8 +129,8 @@ simdjson's source structure, from the top level, looks like this:
   * simdjson/ondemand.h: the `simdjson::ondemand` namespace. Includes all public ondemand classes.
     * simdjson/builtin.h: the `simdjson::builtin` namespace. Aliased to the most universal implementation available.
     * simdjson/builtin/ondemand.h: the `simdjson::builtin::ondemand` namespace.
-    * simdjson/arm64|fallback|haswell|icelake|ppc64|westmere/ondemand.h: the `simdjson::<implementation>::ondemand` namespace. on demand compiled for the specific implementation.
-    * simdjson/generic/ondemand/*.h: individual on demand classes, generically written.
+    * simdjson/arm64|fallback|haswell|icelake|ppc64|westmere/ondemand.h: the `simdjson::<implementation>::ondemand` namespace. On-Demand compiled for the specific implementation.
+    * simdjson/generic/ondemand/*.h: individual On-Demand classes, generically written.
       * simdjson/generic/ondemand/dependencies.h: dependencies on common, non-implementation-specific simdjson classes. This will be included before including amalgamated.h.
       * simdjson/generic/ondemand/amalgamated.h: all generic ondemand classes for an implementation.
 * **src:** The source files for non-inlined functionality (e.g. the architecture-specific parser
@@ -99,16 +140,13 @@ simdjson's source structure, from the top level, looks like this:
   * *.cpp: other misc. implementations, such as `simdjson::implementation` and the minifier.
   * arm64|fallback|haswell|icelake|ppc64|westmere.cpp: Architecture-specific parser implementations.
     * generic/*.h: `simdjson::<implementation>` namespace. Generic implementation of the parser, particularly the `dom_parser_implementation`.
-    * generic/stage1/*.h: `simdjson::<implementation>::stage1` namespace. Generic implementation of the simd-heavy tokenizer/indexer pass of the simdjson parser. Used for the On Demand interface
+    * generic/stage1/*.h: `simdjson::<implementation>::stage1` namespace. Generic implementation of the simd-heavy tokenizer/indexer pass of the simdjson parser. Used for the On-Demand interface
     * generic/stage2/*.h: `simdjson::<implementation>::stage2` namespace. Generic implementation of the tape creator, which consumes the index from stage 1 and actually parses numbers and string and such. Used for the DOM interface.
 
 Other important files and directories:
-* **.drone.yml:** Definitions for Drone CI.
-* **.appveyor.yml:** Definitions for Appveyor CI (Windows).
-* **.circleci:** Definitions for Circle CI.
 * **.github/workflows:** Definitions for GitHub Actions (CI).
 * **singleheader:** Contains generated `simdjson.h` and `simdjson.cpp` that we release. The files `singleheader/simdjson.h` and `singleheader/simdjson.cpp` should never be edited by hand.
-* **singleheader/amalgamate.py:** Generates `singleheader/simdjson.h` and `singleheader/simdjson.cpp` for release (python script).
+* **singleheader/amalgamate.py:** Generates `singleheader/simdjson.h` and `singleheader/simdjson.cpp` for release (python script). If you add a new implementation (e.g., rvv), you need to edit this file (IMPLEMENTATIONS).
 * **benchmark:** This is where we do benchmarking. Benchmarking is core to every change we make; the
   cardinal rule is don't regress performance without knowing exactly why, and what you're trading
   for it. Many of our benchmarks are microbenchmarks. We are effectively doing controlled scientific experiments for the purpose of understanding what affects our performance. So we simplify as much as possible. We try to avoid irrelevant factors such as page faults, interrupts, unnecessary system calls. We recommend checking the performance as follows:

LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2018-2023 The simdjson authors
+   Copyright 2018-2025 The simdjson authors
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

LICENSE-MIT

@@ -0,0 +1,18 @@
+Copyright 2018-2025 The simdjson authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -1,7 +1,5 @@
+[![][license img]][license] [![][licensemit img]][licensemit]
 
-[![Ubuntu 20.04 CI](https://github.com/simdjson/simdjson/workflows/Ubuntu%2020.04%20CI%20(GCC%209)/badge.svg)](https://simdjson.org/plots.html)
-[![Fuzzing Status](https://oss-fuzz-build-logs.storage.googleapis.com/badges/simdjson.svg)](https://bugs.chromium.org/p/oss-fuzz/issues/list?sort=-opened&can=1&q=proj:simdjson)
-[![][license img]][license]
 
 [![Doxygen Documentation](https://img.shields.io/badge/docs-doxygen-green.svg)](https://simdjson.github.io/simdjson/)
 
@@ -31,6 +29,7 @@ Table of Contents
 * [Documentation](#documentation)
 * [Godbolt](#godbolt)
 * [Performance results](#performance-results)
+* [Packages](#packages)
 * [Bindings and Ports of simdjson](#bindings-and-ports-of-simdjson)
 * [About simdjson](#about-simdjson)
 * [Funding](#funding)
@@ -46,6 +45,7 @@ Real-world usage
 - [Meta Velox](https://velox-lib.io)
 - [Google Pax](https://github.com/google/paxml)
 - [milvus](https://github.com/milvus-io/milvus)
+- [QuestDB](https://questdb.io/blog/questdb-release-8-0-3/)
 - [Clang Build Analyzer](https://github.com/aras-p/ClangBuildAnalyzer)
 - [Shopify HeapProfiler](https://github.com/Shopify/heap-profiler)
 - [StarRocks](https://github.com/StarRocks/starrocks)
@@ -60,9 +60,16 @@ Real-world usage
 - [ada-url](https://github.com/ada-url/ada)
 - [fastgron](https://github.com/adamritter/fastgron)
 - [WasmEdge](https://wasmedge.org)
+- [RonDB](https://github.com/logicalclocks/rondb)
+- [GreptimeDB](https://github.com/GreptimeTeam/greptimedb)
+- [mamba](https://github.com/mamba-org/mamba)
+
 
 If you are planning to use simdjson in a product, please work from one of our releases.
 
+
+
+
 Quick Start
 -----------
 
@@ -79,7 +86,7 @@ The simdjson library is easily consumable with a single .h and .cpp file.
    ```
 2. Create `quickstart.cpp`:
 
-```c++
+```cpp
 #include <iostream>
 #include "simdjson.h"
 using namespace simdjson;
@@ -104,15 +111,19 @@ Documentation
 Usage documentation is available:
 
 * [Basics](doc/basics.md) is an overview of how to use simdjson and its APIs.
+* [Builder](doc/builder.md) is an overview of how to efficiently write JSON strings using simdjson.
 * [Performance](doc/performance.md) shows some more advanced scenarios and how to tune for them.
 * [Implementation Selection](doc/implementation-selection.md) describes runtime CPU detection and
   how you can work with it.
 * [API](https://simdjson.github.io/simdjson/) contains the automatically generated API documentation.
+* [Compile-Time Parsing](doc/compile_time.md) presents our compile-time parsing function (C++26 only).
+
 
 Godbolt
 -------------
 
 Some users may want to browse code along with the compiled assembly. You want to check out the following lists of examples:
+* [C++26 reflection example](https://godbolt.org/z/K3Px64TqK)
 * [simdjson examples with errors handled through exceptions](https://godbolt.org/z/7G5qE4sr9)
 * [simdjson examples with errors without exceptions](https://godbolt.org/z/e9dWb9E4v)
 
@@ -142,6 +153,9 @@ speed for [synthetic files over various sizes generated with a script](https://g
 For NDJSON files, we can exceed 3 GB/s with [our  multithreaded parsing functions](https://github.com/simdjson/simdjson/blob/master/doc/parse_many.md).
 
 
+Packages
+------------------------------
+[![Packaging status](https://repology.org/badge/vertical-allrepos/simdjson.svg)](https://repology.org/project/simdjson/versions)
 
 
 Bindings and Ports of simdjson
@@ -166,7 +180,8 @@ We distinguish between "bindings" (which just wrap the C++ code) and a port to a
 - [simdjsone](https://github.com/saleyn/simdjsone): erlang bindings.
 - [lua-simdjson](https://github.com/FourierTransformer/lua-simdjson): lua bindings.
 - [hermes-json](https://hackage.haskell.org/package/hermes-json): haskell bindings.
-- [simdjzon](https://github.com/travisstaloch/simdjzon): zig port.
+- [zimdjson](https://github.com/EzequielRamis/zimdjson): Zig port.
+- [simdjzon](https://github.com/travisstaloch/simdjzon): Zig port.
 - [JSON-Simd](https://github.com/rawleyfowler/JSON-simd): Raku bindings.
 - [JSON::SIMD](https://metacpan.org/pod/JSON::SIMD): Perl bindings; fully-featured JSON module that uses simdjson for decoding.
 - [gemmaJSON](https://github.com/sainttttt/gemmaJSON): Nim JSON parser based on simdjson bindings.
@@ -179,7 +194,7 @@ The simdjson library takes advantage of modern microarchitectures, parallelizing
 instructions, reducing branch misprediction, and reducing data dependency to take advantage of each
 CPU's multiple execution cores.
 
-Our default front-end is called On Demand, and we wrote a paper about it:
+Our default front-end is called On-Demand, and we wrote a paper about it:
 
 - John Keiser, Daniel Lemire, [On-Demand JSON: A Better Way to Parse Documents?](http://arxiv.org/abs/2312.17149), Software: Practice and Experience 54 (6), 2024.
 
@@ -200,22 +215,34 @@ For the video inclined, <br />
 Funding
 -------
 
-The work is supported by the Natural Sciences and Engineering Research Council of Canada under grant
-number RGPIN-2017-03910.
+The work is supported by the Natural Sciences and Engineering Research Council of Canada under grants
+RGPIN-2017-03910 and RGPIN-2024-03787.
 
 [license]: LICENSE
 [license img]: https://img.shields.io/badge/License-Apache%202-blue.svg
 
+
+[licensemit]: LICENSE-MIT
+[licensemit img]: https://img.shields.io/badge/License-MIT-blue.svg
+
+
 Contributing to simdjson
 ------------------------
 
 Head over to [CONTRIBUTING.md](CONTRIBUTING.md) for information on contributing to simdjson, and
 [HACKING.md](HACKING.md) for information on source, building, and architecture/design.
 
+
+Stars
+------
+
+[![Star History Chart](https://api.star-history.com/svg?repos=simdjson/simdjson&type=Date)](https://www.star-history.com/#simdjson/simdjson&Date)
+
+
 License
 -------
 
-This code is made available under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0.html).
+This code is made available under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0.html) as well as under the MIT License. As a user, you can pick the license you prefer.
 
 Under Windows, we build some tools using the windows/dirent_portable.h file (which is outside our library code): it is under the liberal (business-friendly) MIT license.
 

benchmark/CMakeLists.txt

@@ -4,6 +4,9 @@ add_subdirectory(dom)
 include_directories( . linux )
 link_libraries(simdjson-windows-headers test-data)
 link_libraries(simdjson)
+if(SIMDJSON_STATIC_REFLECTION)
+  add_compile_definitions(SIMDJSON_STATIC_REFLECTION=1)
+endif(SIMDJSON_STATIC_REFLECTION)
 
 add_executable(benchfeatures benchfeatures.cpp)
 add_executable(get_corpus_benchmark get_corpus_benchmark.cpp)
@@ -32,3 +35,16 @@ if (TARGET benchmark::benchmark)
   endif()
 endif()
 
+
+include(CheckCXXCompilerFlag)
+check_cxx_compiler_flag("-std=c++20" SIMDJSON_COMPILER_SUPPORTS_CXX20)
+if(SIMDJSON_STATIC_REFLECTION)
+  add_subdirectory(static_reflect)
+else()
+  if(SIMDJSON_EXCEPTIONS AND SIMDJSON_COMPILER_SUPPORTS_CXX20)
+    add_subdirectory(from)
+    add_subdirectory(car_builder)
+  endif()
+endif(SIMDJSON_STATIC_REFLECTION)
+
+

benchmark/accessor_performance/README.md

@@ -0,0 +1,46 @@
+# Accessor Performance Benchmarks (C++26)
+
+These benchmarks compare the performance of runtime vs compile-time JSON accessors.
+For the comparison to be meaningful, you must build simdjson with support for
+C++26 reflexion. See the `p2996` repository in the main project directory.
+
+## Files
+
+- `accessor_benchmark.h` - Common benchmark framework and test data
+- `runtime_accessors.h` - Runtime `at_path()` benchmarks
+- `compile_time_accessors.h` - Compile-time `at_path_compiled()` benchmarks (requires C++26 reflection)
+
+## Benchmarks
+
+Each benchmark measures parsing + single field access:
+
+1. **accessor_simple** - Simple field: `.name`
+2. **accessor_nested** - Nested field: `.address.city`
+3. **accessor_deep** - Deep nested field: `.address.coordinates.lat`
+
+## Building (Linux/macOS)
+
+```bash
+cmake -B build -D SIMDJSON_STATIC_REFLECTION=ON -DSIMDJSON_DEVELOPER_MODE=ON
+cmake --build build --target=bench_ondemand
+```
+
+The `SIMDJSON_STATIC_REFLECTION` will be made unnecessary once mainstream compilers
+begin supporting C++26 sufficiently well.
+
+## Running (Linux/macOS)
+
+
+```bash
+# Run all accessor benchmarks
+./build/bench_ondemand --benchmark_filter="accessor"
+```
+
+## Results
+
+We find that compile-time accessors show performance improvements that scale with path depth:
+- Simple fields: ~1.2x faster
+- Nested fields: ~1.5x faster
+- Deep nested fields: ~1.8x faster
+
+The speedup comes from eliminating runtime path parsing and conversion overhead.

benchmark/accessor_performance/accessor_benchmark.h

@@ -0,0 +1,132 @@
+#pragma once
+
+#include "json_benchmark/file_runner.h"
+#include <string>
+
+namespace accessor_performance {
+
+using namespace json_benchmark;
+
+// Test JSON for accessor benchmarks
+static const char* TEST_JSON = R"({
+  "name": "Alice",
+  "age": 30,
+  "email": "alice@example.com",
+  "address": {
+    "street": "123 Main St",
+    "city": "Boston",
+    "state": "MA",
+    "zip": 12345,
+    "coordinates": {
+      "lat": 42.3601,
+      "lon": -71.0589
+    }
+  },
+  "scores": [95, 87, 92, 88, 91],
+  "preferences": {
+    "theme": "dark",
+    "notifications": {
+      "email": true,
+      "push": false,
+      "sms": true
+    }
+  }
+})";
+
+// Struct definitions for compile-time validation
+#if SIMDJSON_STATIC_REFLECTION
+struct Coordinates {
+  double lat;
+  double lon;
+};
+
+struct Address {
+  std::string street;
+  std::string city;
+  std::string state;
+  int64_t zip;
+  Coordinates coordinates;
+};
+
+struct Notifications {
+  bool email;
+  bool push;
+  bool sms;
+};
+
+struct Preferences {
+  std::string theme;
+  Notifications notifications;
+};
+
+struct TestData {
+  std::string name;
+  int64_t age;
+  std::string email;
+  Address address;
+  std::vector<int64_t> scores;
+  Preferences preferences;
+};
+#endif // SIMDJSON_STATIC_REFLECTION
+
+// Single-access benchmark runner: measures ONE field access per iteration
+template<typename I>
+struct single_access_runner : public file_runner<I> {
+  std::string result_string;
+  int64_t result_int{};
+  double result_double{};
+  bool result_bool{};
+
+  bool setup(benchmark::State &state) {
+    this->json = simdjson::padded_string(TEST_JSON, strlen(TEST_JSON));
+    state.SetBytesProcessed(int64_t(state.iterations()) * int64_t(this->json.size()));
+    return true;
+  }
+
+  bool before_run(benchmark::State &state) {
+    if (!file_runner<I>::before_run(state)) { return false; }
+    result_string.clear();
+    result_int = 0;
+    result_double = 0.0;
+    result_bool = false;
+    return true;
+  }
+
+  bool run(benchmark::State &) {
+    return this->implementation.run(this->json, result_string, result_int, result_double, result_bool);
+  }
+
+  template<typename R>
+  bool diff(benchmark::State &state, single_access_runner<R> &reference) {
+    if (result_string != reference.result_string ||
+        result_int != reference.result_int ||
+        result_double != reference.result_double ||
+        result_bool != reference.result_bool) {
+      std::cerr << "Accessor benchmark results differ!" << std::endl;
+      return false;
+    }
+    return true;
+  }
+
+  size_t items_per_iteration() {
+    return 1;
+  }
+};
+
+// Benchmark template definitions
+struct runtime_at_path_simple;
+template<typename I> simdjson_inline static void accessor_simple(benchmark::State &state) {
+  run_json_benchmark<single_access_runner<I>, single_access_runner<runtime_at_path_simple>>(state);
+}
+
+struct runtime_at_path_nested;
+template<typename I> simdjson_inline static void accessor_nested(benchmark::State &state) {
+  run_json_benchmark<single_access_runner<I>, single_access_runner<runtime_at_path_nested>>(state);
+}
+
+struct runtime_at_path_deep;
+template<typename I> simdjson_inline static void accessor_deep(benchmark::State &state) {
+  run_json_benchmark<single_access_runner<I>, single_access_runner<runtime_at_path_deep>>(state);
+}
+
+} // namespace accessor_performance

benchmark/accessor_performance/compile_time_accessors.h

@@ -0,0 +1,56 @@
+#pragma once
+
+#if SIMDJSON_EXCEPTIONS && SIMDJSON_STATIC_REFLECTION
+
+#include "accessor_benchmark.h"
+
+namespace accessor_performance {
+
+using namespace simdjson;
+
+struct compile_time_at_path_simple {
+  ondemand::parser parser{};
+
+  bool run(simdjson::padded_string &json, std::string &result_str, int64_t&, double&, bool&) {
+    auto doc = parser.iterate(json);
+    std::string_view name;
+    auto r = ondemand::json_path::at_path_compiled<TestData, ".name">(doc);
+    if (r.get(name) != SUCCESS) return false;
+    result_str = name;
+    return true;
+  }
+};
+
+struct compile_time_at_path_nested {
+  ondemand::parser parser{};
+
+  bool run(simdjson::padded_string &json, std::string &result_str, int64_t&, double&, bool&) {
+    auto doc = parser.iterate(json);
+    std::string_view city;
+    auto r = ondemand::json_path::at_path_compiled<TestData, ".address.city">(doc);
+    if (r.get(city) != SUCCESS) return false;
+    result_str = city;
+    return true;
+  }
+};
+
+struct compile_time_at_path_deep {
+  ondemand::parser parser{};
+
+  bool run(simdjson::padded_string &json, std::string&, int64_t&, double &result_dbl, bool&) {
+    auto doc = parser.iterate(json);
+    double lat;
+    auto r = ondemand::json_path::at_path_compiled<TestData, ".address.coordinates.lat">(doc);
+    if (r.get(lat) != SUCCESS) return false;
+    result_dbl = lat;
+    return true;
+  }
+};
+
+BENCHMARK_TEMPLATE(accessor_simple, compile_time_at_path_simple)->UseManualTime();
+BENCHMARK_TEMPLATE(accessor_nested, compile_time_at_path_nested)->UseManualTime();
+BENCHMARK_TEMPLATE(accessor_deep, compile_time_at_path_deep)->UseManualTime();
+
+} // namespace accessor_performance
+
+#endif // SIMDJSON_EXCEPTIONS && SIMDJSON_STATIC_REFLECTION

benchmark/accessor_performance/runtime_accessors.h

@@ -0,0 +1,53 @@
+#pragma once
+
+#if SIMDJSON_EXCEPTIONS
+
+#include "accessor_benchmark.h"
+
+namespace accessor_performance {
+
+using namespace simdjson;
+
+struct runtime_at_path_simple {
+  ondemand::parser parser{};
+
+  bool run(simdjson::padded_string &json, std::string &result_str, int64_t&, double&, bool&) {
+    auto doc = parser.iterate(json);
+    std::string_view name;
+    if (doc.at_path(".name").get(name) != SUCCESS) return false;
+    result_str = name;
+    return true;
+  }
+};
+
+struct runtime_at_path_nested {
+  ondemand::parser parser{};
+
+  bool run(simdjson::padded_string &json, std::string &result_str, int64_t&, double&, bool&) {
+    auto doc = parser.iterate(json);
+    std::string_view city;
+    if (doc.at_path(".address.city").get(city) != SUCCESS) return false;
+    result_str = city;
+    return true;
+  }
+};
+
+struct runtime_at_path_deep {
+  ondemand::parser parser{};
+
+  bool run(simdjson::padded_string &json, std::string&, int64_t&, double &result_dbl, bool&) {
+    auto doc = parser.iterate(json);
+    double lat;
+    if (doc.at_path(".address.coordinates.lat").get(lat) != SUCCESS) return false;
+    result_dbl = lat;
+    return true;
+  }
+};
+
+BENCHMARK_TEMPLATE(accessor_simple, runtime_at_path_simple)->UseManualTime();
+BENCHMARK_TEMPLATE(accessor_nested, runtime_at_path_nested)->UseManualTime();
+BENCHMARK_TEMPLATE(accessor_deep, runtime_at_path_deep)->UseManualTime();
+
+} // namespace accessor_performance
+
+#endif // SIMDJSON_EXCEPTIONS

benchmark/bench_ondemand.cpp

@@ -148,4 +148,9 @@ SIMDJSON_POP_DISABLE_WARNINGS
 #include "large_amazon_cellphones/simdjson_dom.h"
 #include "large_amazon_cellphones/simdjson_ondemand.h"
 
+#include "accessor_performance/runtime_accessors.h"
+#if SIMDJSON_STATIC_REFLECTION
+#include "accessor_performance/compile_time_accessors.h"
+#endif
+
 BENCHMARK_MAIN();

benchmark/benchmark_reflection_usage_compilation.sh

@@ -0,0 +1,618 @@
+#!/bin/bash
+
+# JSON Parsing Compilation Benchmark: Reflection Usage vs Manual Parsing
+# Compares compilation times when ACTUALLY USING reflection for parsing vs manual parsing
+# This measures the compile-time cost of reflection-based automatic deserialization
+
+set -e
+
+echo "=== simdjson Reflection Usage Compilation Benchmark ==="
+echo "Measuring compilation impact of ACTUALLY USING reflection for parsing"
+echo "Starting at: $(date)"
+echo
+echo "╔════════════════════════════════════════════════════════════════════════════╗"
+echo "║                              METHODOLOGY                                   ║"
+echo "╠════════════════════════════════════════════════════════════════════════════╣"
+echo "║                                                                            ║"
+echo "║ FAIR COMPARISON STRATEGY:                                                  ║"
+echo "║ This benchmark compares two DIFFERENT approaches to parsing the same JSON: ║"
+echo "║                                                                            ║"
+echo "║ • MANUAL PARSING: Traditional simdjson with explicit .get() calls          ║"
+echo "║   - Uses doc[\"field\"].get(variable) for each field                         ║"
+echo "║   - No reflection involved                                                 ║"
+echo "║                                                                            ║"
+echo "║ • REFLECTION PARSING: Automatic deserialization with reflection            ║"
+echo "║   - Uses doc.get<MyStruct>() for automatic field mapping                   ║"
+echo "║   - Relies on compile-time reflection to generate parsing code             ║"
+echo "║                                                                            ║"
+echo "║ WHAT WE'RE MEASURING:                                                      ║"
+echo "║ • Compile-time cost of reflection-based automatic deserialization          ║"
+echo "║ • Template instantiation overhead for reflection parsing                   ║"
+echo "║ • Code generation complexity from using reflection features                ║"
+echo "║                                                                            ║"
+echo "║ TEST SCENARIOS:                                                            ║"
+echo "║                                                                            ║"
+echo "║ 1. SIMPLE STRUCT: Basic fields (string, int, bool)                         ║"
+echo "║    - Measures baseline reflection overhead                                 ║"
+echo "║                                                                            ║"
+echo "║ 2. NESTED STRUCT: Multiple levels of nested objects                        ║"
+echo "║    - Measures reflection complexity scaling                                ║"
+echo "║                                                                            ║"
+echo "║ 3. COMPLEX STRUCT: Arrays, optional fields, mixed types                    ║"
+echo "║    - Measures real-world reflection usage impact                           ║"
+echo "║                                                                            ║"
+echo "║ WHY THIS IS MEANINGFUL:                                                    ║"
+echo "║ • Shows actual cost of using reflection features                           ║"
+echo "║ • Measures compile-time code generation overhead                           ║"
+echo "║ • Helps developers understand reflection's compilation impact              ║"
+echo "║ • Compares equivalent functionality implemented two different ways         ║"
+echo "║                                                                            ║"
+echo "╚════════════════════════════════════════════════════════════════════════════╝"
+echo
+
+# Configuration
+ITERATIONS=10
+JOBS=4
+
+# ───────────────────────────── BOX-PRINT HELPER ────────────────────────────
+BOX_WIDTH=74                               # characters between the pipes
+print_box_line() {                         # usage: print_box_line "text"
+  printf "║ %-*s ║\n" "${BOX_WIDTH}" "$1"
+}
+
+# Function to test if a compiler supports reflection with debug output
+test_reflection_support() {
+    local compiler="$1"
+    echo "  → Testing compiler: $compiler"
+
+    if [ ! -x "$compiler" ] && ! command -v "$compiler" >/dev/null 2>&1; then
+        echo "  → Compiler not found or not executable"
+        return 1
+    fi
+
+    # Check compiler version first
+    echo "  → Compiler version: $("$compiler" --version 2>/dev/null | head -n1 || echo "version check failed")"
+
+    # Simple test: check if compiler accepts reflection flags
+    local test_file=$(mktemp /tmp/reflection_test_XXXXXX.cpp)
+    cat > "$test_file" << 'EOF'
+int main() {
+    return 0;
+}
+EOF
+
+    echo "  → Testing basic reflection flags..."
+    local test_exe=$(mktemp /tmp/reflection_test_XXXXXX)
+    local basic_result=$("$compiler" -freflection -fexpansion-statements -std=c++26 "$test_file" -o "$test_exe" 2>&1)
+    local basic_exit_code=$?
+
+    if [ $basic_exit_code -ne 0 ]; then
+        echo "  → Basic flags FAILED with exit code $basic_exit_code"
+        echo "  → Error output: $basic_result"
+        rm -f "$test_file" "$test_exe"
+        return 1
+    fi
+    echo "  → Basic flags: OK"
+    rm -f "$test_exe"
+
+    # Test reflection syntax
+    echo "  → Testing reflection syntax..."
+    cat > "$test_file" << 'EOF'
+struct Test {
+    int x;
+};
+
+int main() {
+    auto refl = ^^Test;
+    return 0;
+}
+EOF
+
+    local syntax_result=$("$compiler" -freflection -fexpansion-statements -std=c++26 "$test_file" -o "$test_exe" 2>&1)
+    local syntax_exit_code=$?
+
+    if [ $syntax_exit_code -eq 0 ]; then
+        echo "  → Reflection syntax: OK"
+        echo "  → ✓ REFLECTION SUPPORT CONFIRMED"
+        rm -f "$test_file" "$test_exe"
+        return 0
+    else
+        echo "  → Reflection syntax FAILED with exit code $syntax_exit_code"
+        echo "  → Error output: $syntax_result"
+        rm -f "$test_file" "$test_exe"
+        return 1
+    fi
+}
+
+# Find a compiler with reflection support
+echo "Searching for clang++ with reflection support..."
+
+REFLECTION_CXX=""
+REFLECTION_CC=""
+
+# List of potential clang++ locations to check
+POTENTIAL_COMPILERS=(
+    "/usr/local/bin/clang++"
+    "/opt/clang/bin/clang++"
+    "/usr/bin/clang++"
+    "clang++"
+)
+
+# If CXX is already set, test it first
+if [ -n "$CXX" ]; then
+    echo "Testing user-specified compiler: $CXX"
+    if test_reflection_support "$CXX"; then
+        REFLECTION_CXX="$CXX"
+        echo "✓ User-specified compiler supports reflection: $CXX"
+    else
+        echo "✗ User-specified compiler does not support reflection: $CXX"
+        echo "Will search for alternative..."
+    fi
+fi
+
+# If we don't have a working compiler yet, search for one
+if [ -z "$REFLECTION_CXX" ]; then
+    for compiler in "${POTENTIAL_COMPILERS[@]}"; do
+        echo "Testing: $compiler"
+        if test_reflection_support "$compiler"; then
+            REFLECTION_CXX="$compiler"
+            echo "✓ Found reflection-enabled compiler: $compiler"
+            break
+        else
+            echo "✗ No reflection support: $compiler"
+        fi
+    done
+fi
+
+# Check if we found a working compiler
+if [ -z "$REFLECTION_CXX" ]; then
+    echo
+    echo "╔════════════════════════════════════════════════════════════════════════════╗"
+    echo "║                                 ERROR                                      ║"
+    echo "╠════════════════════════════════════════════════════════════════════════════╣"
+    echo "║                                                                            ║"
+    echo "║ No clang++ compiler with reflection support found!                        ║"
+    echo "║                                                                            ║"
+    echo "║ This benchmark requires a compiler that supports C++26 reflection.        ║"
+    echo "║                                                                            ║"
+    echo "║ Options:                                                                   ║"
+    echo "║ 1. Use the Docker container: ./p2996/run_docker.sh                        ║"
+    echo "║ 2. Build clang with reflection from: https://github.com/bloomberg/clang-p2996 ║"
+    echo "║ 3. Set CXX environment variable to point to reflection-enabled clang++    ║"
+    echo "║                                                                            ║"
+    echo "║ Example: CXX=/path/to/reflection-clang++ ./benchmark_script.sh            ║"
+    echo "║                                                                            ║"
+    echo "╚════════════════════════════════════════════════════════════════════════════╝"
+    exit 1
+fi
+
+# Set the compilers
+export CXX="$REFLECTION_CXX"
+
+# Find corresponding C compiler
+if [ -n "$CC" ]; then
+    REFLECTION_CC="$CC"
+elif [ "$REFLECTION_CXX" = "/usr/local/bin/clang++" ]; then
+    REFLECTION_CC="/usr/local/bin/clang"
+elif [ "$REFLECTION_CXX" = "/opt/clang/bin/clang++" ]; then
+    REFLECTION_CC="/opt/clang/bin/clang"
+elif [ "$REFLECTION_CXX" = "/usr/bin/clang++" ]; then
+    REFLECTION_CC="/usr/bin/clang"
+else
+    REFLECTION_CC="clang"
+fi
+
+export CC="$REFLECTION_CC"
+
+echo
+echo "Using reflection-enabled compiler: $($CXX --version | head -n1)"
+echo "Using C compiler: $($CC --version | head -n1)"
+echo
+
+# Function to create manual parsing test
+create_manual_parsing_test() {
+    local test_name="$1"
+    local struct_complexity="$2"
+
+    cat > "${test_name}_manual.cpp" << 'EOF'
+#include <simdjson.h>
+#include <iostream>
+#include <string>
+#include <vector>
+#include <optional>
+
+// Test structures
+struct Person {
+    std::string name;
+    int age;
+    bool active;
+};
+
+struct Address {
+    std::string street;
+    std::string city;
+    int zipcode;
+};
+
+struct Employee {
+    Person person;
+    Address address;
+    std::vector<std::string> skills;
+    std::optional<std::string> department;
+    double salary;
+};
+
+// Manual parsing functions
+bool parse_person_manual(simdjson::ondemand::value& val, Person& person) {
+    auto obj = val.get_object();
+    if (obj.error()) return false;
+
+    for (auto field : obj) {
+        std::string_view key = field.unescaped_key();
+        if (key == "name") {
+            std::string_view name_val;
+            if (field.value().get(name_val)) return false;
+            person.name = name_val;
+        } else if (key == "age") {
+            if (field.value().get(person.age)) return false;
+        } else if (key == "active") {
+            if (field.value().get(person.active)) return false;
+        }
+    }
+    return true;
+}
+
+bool parse_address_manual(simdjson::ondemand::value& val, Address& address) {
+    auto obj = val.get_object();
+    if (obj.error()) return false;
+
+    for (auto field : obj) {
+        std::string_view key = field.unescaped_key();
+        if (key == "street") {
+            std::string_view street_val;
+            if (field.value().get(street_val)) return false;
+            address.street = street_val;
+        } else if (key == "city") {
+            std::string_view city_val;
+            if (field.value().get(city_val)) return false;
+            address.city = city_val;
+        } else if (key == "zipcode") {
+            if (field.value().get(address.zipcode)) return false;
+        }
+    }
+    return true;
+}
+
+bool parse_employee_manual(simdjson::ondemand::document& doc, Employee& employee) {
+    auto obj = doc.get_object();
+    if (obj.error()) return false;
+
+    for (auto field : obj) {
+        std::string_view key = field.unescaped_key();
+        if (key == "person") {
+            auto person_val = field.value();
+            if (!parse_person_manual(person_val, employee.person)) return false;
+        } else if (key == "address") {
+            auto addr_val = field.value();
+            if (!parse_address_manual(addr_val, employee.address)) return false;
+        } else if (key == "skills") {
+            auto skills_array = field.value().get_array();
+            if (skills_array.error()) return false;
+            for (auto skill : skills_array) {
+                std::string_view skill_val;
+                if (skill.get(skill_val)) return false;
+                employee.skills.emplace_back(skill_val);
+            }
+        } else if (key == "department") {
+            std::string_view dept_val;
+            if (!field.value().get(dept_val)) {
+                employee.department = dept_val;
+            }
+        } else if (key == "salary") {
+            if (field.value().get(employee.salary)) return false;
+        }
+    }
+    return true;
+}
+
+int main() {
+    simdjson::ondemand::parser parser;
+    std::string json_str = R"({
+        "person": {
+            "name": "John Doe",
+            "age": 30,
+            "active": true
+        },
+        "address": {
+            "street": "123 Main St",
+            "city": "Anytown",
+            "zipcode": 12345
+        },
+        "skills": ["C++", "JSON", "Programming"],
+        "department": "Engineering",
+        "salary": 85000.50
+    })";
+
+    simdjson::ondemand::document doc;
+    auto error = parser.iterate(simdjson::pad(json_str)).get(doc);
+    if (error) {
+        std::cerr << "Parse error" << std::endl;
+        return 1;
+    }
+
+    Employee employee;
+    if (!parse_employee_manual(doc, employee)) {
+        std::cerr << "Manual parsing failed" << std::endl;
+        return 1;
+    }
+
+    std::cout << "Manual parsing successful: " << employee.person.name
+              << ", age " << employee.person.age << std::endl;
+    return 0;
+}
+EOF
+}
+
+# Function to create reflection parsing test
+create_reflection_parsing_test() {
+    local test_name="$1"
+    local struct_complexity="$2"
+
+    cat > "${test_name}_reflection.cpp" << 'EOF'
+#include <simdjson.h>
+#include <iostream>
+#include <string>
+#include <vector>
+#include <optional>
+
+// Test structures (same as manual version)
+struct Person {
+    std::string name;
+    int age;
+    bool active;
+};
+
+struct Address {
+    std::string street;
+    std::string city;
+    int zipcode;
+};
+
+struct Employee {
+    Person person;
+    Address address;
+    std::vector<std::string> skills;
+    std::optional<std::string> department;
+    double salary;
+};
+
+int main() {
+    simdjson::ondemand::parser parser;
+    std::string json_str = R"({
+        "person": {
+            "name": "John Doe",
+            "age": 30,
+            "active": true
+        },
+        "address": {
+            "street": "123 Main St",
+            "city": "Anytown",
+            "zipcode": 12345
+        },
+        "skills": ["C++", "JSON", "Programming"],
+        "department": "Engineering",
+        "salary": 85000.50
+    })";
+
+    simdjson::ondemand::document doc;
+    auto error = parser.iterate(simdjson::pad(json_str)).get(doc);
+    if (error) {
+        std::cerr << "Parse error" << std::endl;
+        return 1;
+    }
+
+    // Use reflection-based automatic deserialization
+    Employee employee;
+    auto result = doc.get<Employee>();
+    if (result.error()) {
+        std::cerr << "Reflection parsing failed" << std::endl;
+        return 1;
+    }
+    employee = result.value();
+
+    std::cout << "Reflection parsing successful: " << employee.person.name
+              << ", age " << employee.person.age << std::endl;
+    return 0;
+}
+EOF
+}
+
+# Function to time compilation of parsing approach
+time_parsing_compilation() {
+    local description="$1"
+    local test_file="$2"
+    local use_reflection="$3"
+    local iteration="$4"
+
+    echo "[$iteration] $description"
+
+    # Clean build
+    rm -rf build_parsing_test
+    mkdir build_parsing_test
+    cd build_parsing_test
+
+    # Copy test file
+    cp "../$test_file" .
+
+    echo "  Configuring..."
+    if [ "$use_reflection" = "true" ]; then
+        cmake -DCMAKE_CXX_COMPILER="$CXX" \
+              -DSIMDJSON_DEVELOPER_MODE=ON \
+              -DSIMDJSON_STATIC_REFLECTION=ON \
+              -DBUILD_SHARED_LIBS=OFF \
+              ../.. >/dev/null 2>&1
+    else
+        cmake -DCMAKE_CXX_COMPILER="$CXX" \
+              -DSIMDJSON_DEVELOPER_MODE=ON \
+              -DSIMDJSON_STATIC_REFLECTION=OFF \
+              -DBUILD_SHARED_LIBS=OFF \
+              ../.. >/dev/null 2>&1
+    fi
+
+    echo "  Building simdjson..."
+    cmake --build . --target simdjson >/dev/null 2>&1
+
+    echo "  Compiling parsing test..."
+    # Time just the test compilation
+    start_time=$(date +%s.%N)
+
+    "$CXX" -std=c++17 -I../../include "$test_file" -L. -lsimdjson -o parsing_test >/dev/null 2>&1
+
+    end_time=$(date +%s.%N)
+
+    # Calculate time duration
+    time_taken=$(echo "$end_time $start_time" | awk '{printf "%.3f", $1 - $2}')
+    echo "  Completed in: ${time_taken}s"
+
+    cd ..
+    rm -rf build_parsing_test
+
+    echo "$time_taken"
+}
+
+# Create test files
+echo "Creating test files..."
+create_manual_parsing_test "complex" "complex"
+create_reflection_parsing_test "complex" "complex"
+
+# Arrays to store times
+times_manual=""
+times_reflection=""
+
+echo
+echo "=== MANUAL PARSING COMPILATION ==="
+echo "Testing traditional simdjson parsing with explicit .get() calls"
+echo
+
+for i in $(seq 1 $ITERATIONS); do
+    time_result=$(time_parsing_compilation "Compiling manual parsing test" "complex_manual.cpp" "false" "$i" | tail -n1)
+    times_manual="$times_manual $time_result"
+done
+
+echo
+echo "=== REFLECTION PARSING COMPILATION ==="
+echo "Testing automatic deserialization with doc.get<Struct>()"
+echo
+
+for i in $(seq 1 $ITERATIONS); do
+    time_result=$(time_parsing_compilation "Compiling reflection parsing test" "complex_reflection.cpp" "true" "$i" | tail -n1)
+    times_reflection="$times_reflection $time_result"
+done
+
+echo
+echo "╔════════════════════════════════════════════════════════════════════════════╗"
+echo "║           REFLECTION USAGE COMPILATION RESULTS                             ║"
+echo "╠════════════════════════════════════════════════════════════════════════════╣"
+echo "║                                                                            ║"
+echo "║ MANUAL PARSING (explicit .get() calls):                                    ║"
+count=1
+for t in $times_manual; do
+    if [[ "$t" =~ ^[0-9]+\.?[0-9]*$ ]]; then
+        line=$(printf "Run %2d: %7.3f seconds" "$count" "$t")
+        print_box_line "$line"
+        count=$((count + 1))
+    fi
+done
+echo "║                                                                            ║"
+echo "║ REFLECTION PARSING (automatic doc.get<Struct>()):                          ║"
+count=1
+for t in $times_reflection; do
+    if [[ "$t" =~ ^[0-9]+\.?[0-9]*$ ]]; then
+        line=$(printf "Run %2d: %7.3f seconds" "$count" "$t")
+        print_box_line "$line"
+        count=$((count + 1))
+    fi
+done
+echo "╚════════════════════════════════════════════════════════════════════════════╝"
+
+echo
+echo "╔════════════════════════════════════════════════════════════════════════════╗"
+echo "║                              ANALYSIS SUMMARY                              ║"
+echo "╠════════════════════════════════════════════════════════════════════════════╣"
+echo "║                                                                            ║"
+
+# Calculate averages and percentages - filter to only numeric values first
+manual_numbers=""
+reflection_numbers=""
+
+for t in $times_manual; do
+    if [[ "$t" =~ ^[0-9]+\.?[0-9]*$ ]]; then
+        manual_numbers="$manual_numbers $t"
+    fi
+done
+
+for t in $times_reflection; do
+    if [[ "$t" =~ ^[0-9]+\.?[0-9]*$ ]]; then
+        reflection_numbers="$reflection_numbers $t"
+    fi
+done
+
+if [ -n "$manual_numbers" ] && [ -n "$reflection_numbers" ]; then
+    manual_avg=$(echo "$manual_numbers" | awk '{sum=0; for(i=1;i<=NF;i++) sum+=$i; print sum/NF}')
+    reflection_avg=$(echo "$reflection_numbers" | awk '{sum=0; for(i=1;i<=NF;i++) sum+=$i; print sum/NF}')
+    overhead=$(echo "$reflection_avg $manual_avg" | awk '{printf "%.3f", $1 - $2}')
+
+    if [ $(echo "$manual_avg > 0" | awk '{print ($1 > 0)}') -eq 1 ]; then
+        percent=$(echo "$reflection_avg $manual_avg" | awk '{printf "%.1f", ($1 - $2) / $2 * 100}')
+    else
+        percent="0"
+    fi
+
+    print_box_line "MANUAL PARSING RESULTS:"
+    print_box_line "$(printf "Average compilation time: %.3fs" "$manual_avg")"
+    print_box_line ""
+    print_box_line "REFLECTION PARSING RESULTS:"
+    print_box_line "$(printf "Average compilation time: %.3fs" "$reflection_avg")"
+    print_box_line ""
+    print_box_line "REFLECTION OVERHEAD:"
+    print_box_line "$(printf "Additional time: %.3fs (%+.1f%%)" "$overhead" "$percent")"
+    print_box_line ""
+else
+    echo "║ ERROR: Could not extract valid timing data                                 ║"
+    echo "║ Manual times: $times_manual"
+    echo "║ Reflection times: $times_reflection"
+    echo "║                                                                            ║"
+fi
+
+echo "╠════════════════════════════════════════════════════════════════════════════╣"
+echo "║                              INTERPRETATION                                ║"
+echo "╠════════════════════════════════════════════════════════════════════════════╣"
+echo "║                                                                            ║"
+echo "║ WHAT THESE RESULTS SHOW:                                                   ║"
+echo "║                                                                            ║"
+echo "║ • COMPILE-TIME COST: How much longer reflection parsing takes to compile   ║"
+echo "║   - Higher % = more expensive template instantiation and codegen           ║"
+echo "║                                                                            ║"
+echo "║ • CODE GENERATION OVERHEAD: Reflection creates parsing code at compile     ║"
+echo "║   time, which requires more template processing than manual parsing        ║"
+echo "║                                                                            ║"
+echo "║ • DEVELOPER TRADE-OFF: Reflection provides automatic deserialization       ║"
+echo "║   but at the cost of increased compilation time                            ║"
+echo "║                                                                            ║"
+echo "║ EVALUATION:                                                                ║"
+echo "║ • Low overhead (0-20%): Reflection is compile-time efficient               ║"
+echo "║ • Medium overhead (20-50%): Noticeable but potentially acceptable          ║"
+echo "║ • High overhead (50%+): Significant compilation cost for reflection        ║"
+echo "║                                                                            ║"
+echo "║ REAL-WORLD IMPACT:                                                         ║"
+echo "║ • Small projects: Absolute time matters more than percentage               ║"
+echo "║ • Large projects: Percentage overhead compounds across many files          ║"
+echo "║ • CI/CD pipelines: Longer builds affect development velocity               ║"
+echo "║                                                                            ║"
+echo "╚════════════════════════════════════════════════════════════════════════════╝"
+
+# Clean up test files
+rm -f complex_manual.cpp complex_reflection.cpp
+
+echo
+echo "Completed at: $(date)"

benchmark/car_builder/CMakeLists.txt

@@ -0,0 +1,14 @@
+# Executable
+add_executable(benchmark_car_builder benchmark_car_builder.cpp)
+
+# Compile for C++20.
+target_compile_features(benchmark_car_builder PRIVATE cxx_std_20)
+
+# Check if -march=native is supported
+include(CheckCXXCompilerFlag)
+check_cxx_compiler_flag("-march=native" SIMDJSON_SUPPORTS_MARCH_NATIVE)
+if(SIMDJSON_SUPPORTS_MARCH_NATIVE)
+  target_compile_options(benchmark_car_builder PRIVATE -march=native)
+endif()
+
+target_include_directories(benchmark_car_builder PRIVATE ${CMAKE_CURRENT_LIST_DIR}/..)

benchmark/car_builder/benchmark_car_builder.cpp

@@ -0,0 +1,127 @@
+#include "event_counter.h"
+#include <random>
+#include <vector>
+
+#include <simdjson.h>
+
+event_collector collector;
+
+struct Car {
+  std::string make;
+  std::string model;
+  int64_t year; // We deliberately do not include the tire pressure.
+};
+
+std::vector<Car> generate_random_cars(size_t count) {
+  static const std::vector<std::string> makes = {"Toyota", "Honda", "Ford",
+                                                 "BMW", "Mazda"};
+  static const std::vector<std::string> models = {"Camry", "Civic", "Focus",
+                                                  "320i", "3"};
+  static thread_local std::mt19937 rng{std::random_device{}()};
+  std::uniform_int_distribution<int> make_dist(0, makes.size() - 1);
+  std::uniform_int_distribution<int> model_dist(0, models.size() - 1);
+  std::uniform_int_distribution<int64_t> year_dist(2000, 2025);
+  std::uniform_real_distribution<double> pressure_dist(30.0, 45.0);
+
+  std::vector<Car> cars;
+  cars.reserve(count);
+  for (size_t i = 0; i < count; ++i) {
+    Car car;
+    car.make = makes[make_dist(rng)];
+    car.model = models[model_dist(rng)];
+    car.year = year_dist(rng);
+    cars.push_back(std::move(car));
+  }
+  return cars;
+}
+
+std::string_view serialize(simdjson::builder::string_builder &sb,
+                           const std::vector<Car> &cars) {
+  sb.clear();
+  sb.start_array();
+  for (const auto &car : cars) {
+    sb.start_object();
+    sb.append_key_value("make", car.make);
+    sb.append_comma();
+    sb.append_key_value("model", car.model);
+    sb.append_comma();
+    sb.append_key_value("year", car.year);
+    sb.end_object();
+  }
+  sb.end_array();
+  std::string_view result;
+  if (sb.view().get(result)) {
+    return ""; // unexpected (error)
+  }
+  return result;
+}
+
+double pretty_print(const std::string &name, size_t num_chars,
+                    std::pair<event_aggregate, size_t> result) {
+  const auto &agg = result.first;
+  size_t N = result.second;
+  num_chars *= N;
+  printf("%-40s : %8.2f ns %8.2f GB/s", name.c_str(),
+         agg.elapsed_ns() / num_chars, num_chars / agg.elapsed_ns());
+  if (collector.has_events()) {
+    printf(" %8.2f GHz %8.2f cycles/char %8.2f ins./char %8.2f i/c",
+           agg.cycles() / agg.elapsed_ns(), agg.cycles() / num_chars,
+           agg.instructions() / num_chars, agg.instructions() / agg.cycles());
+  }
+  printf("\n");
+  return num_chars / agg.elapsed_ns();
+}
+
+template <class function_type>
+std::pair<event_aggregate, size_t>
+bench(const function_type &&function, size_t min_repeat = 100,
+      size_t min_time_ns = 40'000'000, size_t max_repeat = 10000000) {
+  size_t N = min_repeat;
+  if (N == 0) {
+    N = 1;
+  }
+  event_aggregate warm_aggregate{};
+  for (size_t i = 0; i < N; i++) {
+    std::atomic_thread_fence(std::memory_order_acquire);
+    collector.start();
+    function();
+    std::atomic_thread_fence(std::memory_order_release);
+    event_count allocate_count = collector.end();
+    warm_aggregate << allocate_count;
+    if ((i + 1 == N) && (warm_aggregate.total_elapsed_ns() < min_time_ns) &&
+        (N < max_repeat)) {
+      N *= 10;
+    }
+  }
+  event_aggregate aggregate{};
+  for (size_t i = 0; i < 10; i++) {
+    std::atomic_thread_fence(std::memory_order_acquire);
+    collector.start();
+    for (size_t i = 0; i < N; i++) {
+      function();
+    }
+    std::atomic_thread_fence(std::memory_order_release);
+    event_count allocate_count = collector.end();
+    aggregate << allocate_count;
+  }
+  return {aggregate, N};
+}
+
+void run_benchmarks() {
+  std::vector<Car> source = generate_random_cars(100000);
+  simdjson::builder::string_builder sb;
+  size_t volume = serialize(sb, source).size();
+
+  pretty_print("string_builder", volume, bench([&source, &sb]() -> size_t {
+                 return serialize(sb, source).size();
+               }));
+}
+
+int main() {
+  for (size_t trial = 0; trial < 3; trial++) {
+    printf("Trial %zu:\n", trial + 1);
+    run_benchmarks();
+    printf("\n");
+  }
+  return EXIT_SUCCESS;
+}

benchmark/distinct_user_id/yyjson.h

@@ -44,7 +44,10 @@ struct yyjson_base {
 
 struct yyjson : yyjson_base {
   bool run(simdjson::padded_string &json, std::vector<uint64_t> &result) {
-    return yyjson_base::run(yyjson_read(json.data(), json.size(), 0), result);
+    yyjson_doc *doc = yyjson_read(json.data(), json.size(), 0);
+    bool b = yyjson_base::run(doc, result);
+    yyjson_doc_free(doc);
+    return b;
   }
 };
 BENCHMARK_TEMPLATE(distinct_user_id, yyjson)->UseManualTime();
@@ -52,11 +55,15 @@ BENCHMARK_TEMPLATE(distinct_user_id, yyjson)->UseManualTime();
 #if SIMDJSON_COMPETITION_ONDEMAND_INSITU
 struct yyjson_insitu : yyjson_base {
   bool run(simdjson::padded_string &json, std::vector<uint64_t> &result) {
-    return yyjson_base::run(yyjson_read_opts(json.data(), json.size(), YYJSON_READ_INSITU, 0, 0), result);
+    yyjson_doc *doc = yyjson_read_opts(json.data(), json.size(), YYJSON_READ_INSITU, 0, 0);
+    bool b = yyjson_base::run(doc, result);
+    yyjson_doc_free(doc);
+    return b;
   }
 };
 BENCHMARK_TEMPLATE(distinct_user_id, yyjson_insitu)->UseManualTime();
 #endif // SIMDJSON_COMPETITION_ONDEMAND_INSITU
+
 } // namespace distinct_user_id
 
 #endif // SIMDJSON_COMPETITION_YYJSON

benchmark/dom/parse_stream.cpp

@@ -25,12 +25,11 @@ int main(int argc, char *argv[]) {
     exit(1);
   }
   const char *filename = argv[1];
-  auto v = simdjson::padded_string::load(filename);
-  if (v.error()) {
+  simdjson::padded_string p;
+  if (simdjson::padded_string::load(filename).get(p)) {
     std::cerr << "Could not load the file " << filename << std::endl;
     return EXIT_FAILURE;
   }
-  const simdjson::padded_string& p = v.value_unsafe();
   if (test_baseline) {
     std::wclog << "Baseline: Getline + normal parse... " << std::endl;
     std::cout << "Gigabytes/second\t"

benchmark/event_counter.h

@@ -122,6 +122,7 @@ struct event_aggregate {
   }
 
   double elapsed_sec() const { return total.elapsed_sec() / iterations; }
+  double total_elapsed_ns() const { return total.elapsed_ns(); }
   double elapsed_ns() const { return total.elapsed_ns() / iterations; }
   double cycles() const { return total.cycles() / iterations; }
   double instructions() const { return total.instructions() / iterations; }

benchmark/find_tweet/nlohmann_json.h

@@ -13,7 +13,7 @@ struct nlohmann_json {
     auto root = nlohmann::json::parse(json.data(), json.data() + json.size());
     for (auto tweet : root["statuses"]) {
       if (tweet["id"] == find_id) {
-        result = tweet["text"];
+        result = to_string(tweet["text"]);
         return true;
       }
     }

benchmark/find_tweet/yyjson.h

@@ -36,18 +36,26 @@ struct yyjson_base {
 
 struct yyjson : yyjson_base {
   bool run(simdjson::padded_string &json, uint64_t find_id, std::string_view &result) {
-    return yyjson_base::run(yyjson_read(json.data(), json.size(), 0), find_id, result);
+    yyjson_doc *doc = yyjson_read(json.data(), json.size(), 0);
+    bool b = yyjson_base::run(doc, find_id, result);
+    yyjson_doc_free(doc);
+    return b;
   }
 };
 BENCHMARK_TEMPLATE(find_tweet, yyjson)->UseManualTime();
+
 #if SIMDJSON_COMPETITION_ONDEMAND_INSITU
 struct yyjson_insitu : yyjson_base {
   bool run(simdjson::padded_string &json, uint64_t find_id, std::string_view &result) {
-    return yyjson_base::run(yyjson_read_opts(json.data(), json.size(), YYJSON_READ_INSITU, 0, 0), find_id, result);
+    yyjson_doc *doc = yyjson_read_opts(json.data(), json.size(), YYJSON_READ_INSITU, 0, 0);
+    bool b = yyjson_base::run(doc, find_id, result);
+    yyjson_doc_free(doc);
+    return b;
   }
 };
 BENCHMARK_TEMPLATE(find_tweet, yyjson_insitu)->UseManualTime();
 #endif // SIMDJSON_COMPETITION_ONDEMAND_INSITU
+
 } // namespace find_tweet
 
 #endif // SIMDJSON_COMPETITION_YYJSON

benchmark/from/CMakeLists.txt

@@ -0,0 +1,15 @@
+# Executable
+add_executable(from_benchmark from_benchmark.cpp)
+
+# Compile for C++20.
+if(CMAKE_CXX_STANDARD LESS 20)
+  target_compile_features(from_benchmark PRIVATE cxx_std_20)
+endif()
+# Check if -march=native is supported
+include(CheckCXXCompilerFlag)
+check_cxx_compiler_flag("-march=native" SIMDJSON_SUPPORTS_MARCH_NATIVE)
+if(SIMDJSON_SUPPORTS_MARCH_NATIVE)
+  target_compile_options(from_benchmark PRIVATE -march=native)
+endif()
+
+target_include_directories(from_benchmark PRIVATE ${CMAKE_CURRENT_LIST_DIR}/..)

benchmark/from/benchmark_helpers.h

@@ -0,0 +1,77 @@
+#ifndef BENCHMARK_HELPERS_H
+#define BENCHMARK_HELPERS_H
+
+#include "event_counter.h"
+#include <atomic>
+
+event_collector collector;
+
+template <class function_type>
+std::pair<event_aggregate, size_t>
+bench(const function_type &&function, size_t min_repeat = 10,
+      size_t min_time_ns = 40'000'000, size_t max_repeat = 10000000) {
+  size_t N = min_repeat;
+  if (N == 0) {
+    N = 1;
+  }
+  event_aggregate warm_aggregate{};
+  for (size_t i = 0; i < N; i++) {
+    std::atomic_thread_fence(std::memory_order_acquire);
+    collector.start();
+    function();
+    std::atomic_thread_fence(std::memory_order_release);
+    event_count allocate_count = collector.end();
+    warm_aggregate << allocate_count;
+    if ((i + 1 == N) && (warm_aggregate.total_elapsed_ns() < min_time_ns) &&
+        (N < max_repeat)) {
+      N *= 10;
+    }
+  }
+  event_aggregate aggregate{};
+  for (size_t i = 0; i < 10; i++) {
+    std::atomic_thread_fence(std::memory_order_acquire);
+    collector.start();
+    for (size_t i = 0; i < N; i++) {
+      function();
+    }
+    std::atomic_thread_fence(std::memory_order_release);
+    event_count allocate_count = collector.end();
+    aggregate << allocate_count;
+  }
+  return {aggregate, N};
+}
+
+double pretty_print(const std::string &name, size_t num_chars,
+                    std::pair<event_aggregate, size_t> result) {
+  const auto &agg = result.first;
+  size_t N = result.second;
+  num_chars *= N;
+  printf("%-40s : %8.2f ns %8.2f GB/s", name.c_str(),
+         agg.elapsed_ns() / num_chars, num_chars / agg.elapsed_ns());
+  if (collector.has_events()) {
+    printf(" %8.2f GHz %8.2f cycles/char %8.2f ins./char %8.2f i/c",
+           agg.cycles() / agg.elapsed_ns(), agg.cycles() / num_chars,
+           agg.instructions() / num_chars, agg.instructions() / agg.cycles());
+  }
+  printf("\n");
+  return num_chars / agg.elapsed_ns();
+}
+
+double pretty_print_array(const std::string &name, size_t num_chars, size_t num_elements,
+                    std::pair<event_aggregate, size_t> result) {
+  const auto &agg = result.first;
+  size_t N = result.second;
+  num_chars *= N;
+  printf("%-40s : %8.2f ns/char %8.2f ns/value %8.2f GB/s", name.c_str(),
+         agg.elapsed_ns() / num_chars, agg.elapsed_ns() / num_elements, num_chars / agg.elapsed_ns());
+  if (collector.has_events()) {
+    printf(" %8.2f GHz %8.2f cycles/char %8.2f ins./char %8.2f ins./value %8.2f i/c",
+           agg.cycles() / agg.elapsed_ns(), agg.cycles() / num_chars,
+           agg.instructions() / num_chars, agg.instructions() / num_elements, agg.instructions() / agg.cycles());
+  }
+  printf("\n");
+  return num_chars / agg.elapsed_ns();
+}
+
+
+#endif

benchmark/from/car_helpers.h

@@ -0,0 +1,146 @@
+#ifndef CAR_HELPERS_H
+#define CAR_HELPERS_H
+
+#include <iomanip>
+#include <random>
+#include <sstream>
+#include <vector>
+
+#include <simdjson.h>
+
+struct Car {
+  std::string make;
+  std::string model;
+  int64_t year; // We deliberately do not include the tire pressure.
+};
+
+using namespace simdjson;
+
+std::string random_car_json() {
+  static const std::vector<std::string> makes = {"Toyota", "Honda", "Ford",
+                                                 "BMW", "Mazda"};
+  static const std::vector<std::string> models = {"Camry", "Civic", "Focus",
+                                                  "320i", "3"};
+  static thread_local std::mt19937 rng{std::random_device{}()};
+  std::uniform_int_distribution<int> make_dist(0, makes.size() - 1);
+  std::uniform_int_distribution<int> model_dist(0, models.size() - 1);
+  std::uniform_int_distribution<int> year_dist(2000, 2025);
+  std::uniform_real_distribution<double> pressure_dist(30.0, 45.0);
+
+  std::ostringstream oss;
+  oss << R"({ "make": ")" << makes[make_dist(rng)] << R"(", "model": ")"
+      << models[model_dist(rng)] << R"(",  "year": )" << year_dist(rng)
+      << R"(, "tire_pressure": [ )" << std::fixed << std::setprecision(1)
+      << pressure_dist(rng) << ", " << pressure_dist(rng) << R"( ] })";
+  return oss.str();
+}
+
+std::string generate_car_json_stream(size_t N) {
+  std::ostringstream oss;
+  for (size_t i = 0; i < N; ++i) {
+    oss << random_car_json();
+    oss << "\n";
+  }
+  return oss.str();
+}
+
+std::string generate_car_json_array(size_t N) {
+  std::ostringstream oss;
+  oss << "[\n";
+  for (size_t i = 0; i < N; ++i) {
+    oss << random_car_json();
+    if (i < N - 1) {
+      oss << ",";
+    }
+    oss << "\n";
+  }
+  oss << "]";
+  return oss.str();
+}
+
+// We want to maximize C++ portability, but this is not needed with static
+// reflection (C++26).
+template <>
+simdjson_inline simdjson_result<Car>
+simdjson::ondemand::document::get() & noexcept {
+  ondemand::object obj;
+  auto error = get_object().get(obj);
+  if (error) {
+    return error;
+  }
+  Car car;
+  if ((error = obj["make"].get_string(car.make))) {
+    return error;
+  }
+  if ((error = obj["model"].get_string(car.model))) {
+    return error;
+  }
+  if ((error = obj["year"].get_int64().get(car.year))) {
+    return error;
+  }
+  return car;
+}
+
+template <>
+simdjson_inline simdjson_result<Car> simdjson::ondemand::value::get() noexcept {
+  ondemand::object obj;
+  auto error = get_object().get(obj);
+  if (error) {
+    return error;
+  }
+  Car car;
+  if ((error = obj["make"].get_string(car.make))) {
+    return error;
+  }
+  if ((error = obj["model"].get_string(car.model))) {
+    return error;
+  }
+  if ((error = obj["year"].get_int64().get(car.year))) {
+    return error;
+  }
+  return car;
+}
+
+template <>
+simdjson_inline simdjson_result<Car>
+simdjson::ondemand::document_reference::get() & noexcept {
+  ondemand::object obj;
+  auto error = get_object().get(obj);
+  if (error) {
+    return error;
+  }
+  Car car;
+  if ((error = obj["make"].get_string(car.make))) {
+    return error;
+  }
+  if ((error = obj["model"].get_string(car.model))) {
+    return error;
+  }
+  if ((error = obj["year"].get_int64().get(car.year))) {
+    return error;
+  }
+  return car;
+}
+
+template <>
+simdjson_inline simdjson_result<Car>
+simdjson::ondemand::document_reference::get() && noexcept {
+  ondemand::object obj;
+  auto error = get_object().get(obj);
+  if (error) {
+    return error;
+  }
+  Car car;
+  if ((error = obj["make"].get_string(car.make))) {
+    return error;
+  }
+  if ((error = obj["model"].get_string(car.model))) {
+    return error;
+  }
+  if ((error = obj["year"].get_int64().get(car.year))) {
+    return error;
+  }
+  return car;
+}
+
+#endif

benchmark/from/from_benchmark.cpp

@@ -0,0 +1,132 @@
+// We are going to assume C++20.
+
+#include <cstdint>
+#include <cstdio>
+#include <cstdlib>
+#include <simdjson.h>
+#include <string>
+
+#include "benchmark_helpers.h"
+#include "car_helpers.h"
+
+using namespace simdjson;
+
+void run_benchmarks() {
+  printf("Running benchmarks on tiny input...\n");
+  simdjson::padded_string json =
+      R"({ "make": "Toyota", "model": "Camry",  "year": 2018, "tire_pressure": [ 40.1, 39.9 ] })"_padded;
+  volatile size_t dummy = 0;
+  ondemand::parser parser;
+
+  // Classic On-Demand
+  pretty_print("simdjson classic", json.size(),
+               bench([&json, &dummy, &parser]() {
+                 ondemand::document doc = parser.iterate(json);
+                 Car car = doc.get<Car>();
+                 dummy = dummy + car.year;
+               }));
+
+  // Benchmark simdjson::from() without parser
+  pretty_print("simdjson::from<Car>() (no parser)", json.size(),
+               bench([&json, &dummy]() {
+                 Car car = simdjson::from(json);
+                 dummy = dummy + car.year;
+               }));
+
+  // Benchmark simdjson::from() with parser
+  pretty_print("simdjson::from<Car>() (with parser)", json.size(),
+               bench([&json, &dummy, &parser]() {
+                 Car car = simdjson::from(parser, json);
+                 dummy = dummy + car.year;
+               }));
+}
+
+void run_array_benchmarks() {
+  printf("Running benchmarks on large array...\n");
+  size_t N = 1'000'000;
+  simdjson::padded_string json = generate_car_json_array(N);
+  volatile size_t dummy = 0;
+  ondemand::parser parser;
+
+  // Classic On-Demand
+  pretty_print_array("simdjson classic", json.size(), N,
+                     bench([&json, &dummy, &parser]() {
+                       dummy = 0;
+                       ondemand::document doc = parser.iterate(json);
+                       ondemand::array array = doc.get_array();
+                       for (auto value : array) {
+                         Car car = value.get<Car>();
+                         dummy = dummy + car.year;
+                       }
+                     }));
+
+  // from with array
+  pretty_print_array("simdjson::from(json).array()", json.size(), N,
+                     bench([&json, &dummy, &parser]() {
+                       dummy = 0;
+
+                       for (auto value : simdjson::from(json).array()) {
+                         Car car = value.get<Car>();
+                         dummy = dummy + car.year;
+                       }
+                     }));
+#if SIMDJSON_SUPPORTS_RANGES_FROM
+  // Benchmark simdjson::from() without parser (EXPERIMENTAL)
+  pretty_print_array("simdjson::from<Car>() (experimental, no parser)",
+                     json.size(), N, bench([&json, &dummy]() {
+                       dummy = 0;
+                       for (Car car :
+                            simdjson::from(json) | simdjson::as<Car>()) {
+                         dummy = dummy + car.year;
+                       }
+                     }));
+
+  // Benchmark simdjson::from() with parser (EXPERIMENTAL)
+  pretty_print_array("simdjson::from<Car>() (experimental, with parser)",
+                     json.size(), N, bench([&json, &dummy, &parser]() {
+                       dummy = 0;
+                       for (Car car : simdjson::from(parser, json) |
+                                          simdjson::as<Car>()) {
+                         dummy = dummy + car.year;
+                       }
+                     }));
+#endif // SIMDJSON_SUPPORTS_RANGES_FROM
+}
+
+void run_stream_benchmarks() {
+  printf("Running stream benchmarks...\n");
+  simdjson::padded_string json = generate_car_json_stream(1'000'000);
+  volatile size_t dummy = 0;
+  ondemand::parser parser;
+
+  // Classic On-Demand
+  pretty_print("simdjson classic", json.size(),
+               bench([&json, &dummy, &parser]() {
+                 ondemand::document_stream stream = parser.iterate_many(json);
+                 for (auto doc : stream) {
+                   Car car = doc.get<Car>();
+                   dummy = dummy + car.year;
+                 }
+               }));
+  // from_many
+  pretty_print("simdjson with thread local", json.size(),
+               bench([&json, &dummy, &parser]() {
+                 ondemand::document_stream stream =
+                     ondemand::parser::get_parser().iterate_many(json);
+                 for (auto doc : stream) {
+                   Car car = doc.get<Car>();
+                   dummy = dummy + car.year;
+                 }
+               }));
+}
+
+int main() {
+  for (size_t trial = 0; trial < 3; trial++) {
+    printf("Trial %zu:\n", trial + 1);
+    run_array_benchmarks();
+    run_stream_benchmarks();
+    run_benchmarks();
+    printf("\n");
+  }
+  return EXIT_SUCCESS;
+}

benchmark/get_corpus_benchmark.cpp

@@ -9,7 +9,11 @@ simdjson_never_inline
 double bench(std::string filename, simdjson::padded_string& p) {
   std::chrono::time_point<std::chrono::steady_clock> start_clock =
       std::chrono::steady_clock::now();
-  simdjson::padded_string::load(filename).value_unsafe().swap(p);
+  auto error = simdjson::padded_string::load(filename).get(p);
+  if(error) {
+    std::cerr << simdjson::error_message(error) << std::endl;
+    std::abort();
+  }
   std::chrono::time_point<std::chrono::steady_clock> end_clock =
       std::chrono::steady_clock::now();
   std::chrono::duration<double> elapsed = end_clock - start_clock;

benchmark/json2msgpack/yyjson.h

@@ -100,6 +100,7 @@ struct yyjson : yyjson2msgpack {
            std::string_view &result) {
     yyjson_doc *doc = yyjson_read(json.data(), json.size(), 0);
     result = to_msgpack(doc, reinterpret_cast<uint8_t*>(buffer));
+    yyjson_doc_free(doc);
     return true;
   }
 };
@@ -113,6 +114,7 @@ struct yyjson_insitu : yyjson2msgpack {
     yyjson_doc *doc =
         yyjson_read_opts(json.data(), json.size(), YYJSON_READ_INSITU, 0, 0);
     result = to_msgpack(doc, reinterpret_cast<uint8_t*>(buffer));
+    yyjson_doc_free(doc);
     return true;
   }
 };
@@ -120,4 +122,4 @@ BENCHMARK_TEMPLATE(json2msgpack, yyjson_insitu)->UseManualTime();
 #endif // SIMDJSON_COMPETITION_ONDEMAND_INSITU
 } // namespace json2msgpack
 
-#endif // SIMDJSON_COMPETITION_YYJSON
+#endif // SIMDJSON_COMPETITION_YYJSON

benchmark/kostya/yyjson.h

@@ -49,18 +49,26 @@ struct yyjson_base {
 
 struct yyjson : yyjson_base {
   bool run(simdjson::padded_string &json, std::vector<point> &result) {
-    return yyjson_base::run(yyjson_read(json.data(), json.size(), 0), result);
+    yyjson_doc *doc = yyjson_read(json.data(), json.size(), 0);
+    bool b = yyjson_base::run(doc, result);
+    yyjson_doc_free(doc);
+    return b;
   }
 };
 BENCHMARK_TEMPLATE(kostya, yyjson)->UseManualTime();
+
 #if SIMDJSON_COMPETITION_ONDEMAND_INSITU
 struct yyjson_insitu : yyjson_base {
   bool run(simdjson::padded_string &json, std::vector<point> &result) {
-    return yyjson_base::run(yyjson_read_opts(json.data(), json.size(), YYJSON_READ_INSITU, 0, 0), result);
+    yyjson_doc *doc = yyjson_read_opts(json.data(), json.size(), YYJSON_READ_INSITU, 0, 0);
+    bool b = yyjson_base::run(doc, result);
+    yyjson_doc_free(doc);
+    return b;
   }
 };
 BENCHMARK_TEMPLATE(kostya, yyjson_insitu)->UseManualTime();
 #endif // SIMDJSON_COMPETITION_ONDEMAND_INSITU
+
 } // namespace kostya
 
 #endif // SIMDJSON_COMPETITION_YYJSON

benchmark/large_random/simdjson_ondemand.h

@@ -23,7 +23,29 @@ struct simdjson_ondemand {
 };
 
 BENCHMARK_TEMPLATE(large_random, simdjson_ondemand)->UseManualTime();
+#if SIMDJSON_STATIC_REFLECTION
 
+struct simdjson_ondemand_static_reflect {
+  static constexpr diff_flags DiffFlags = diff_flags::NONE;
+
+  ondemand::parser parser{};
+
+  bool run(simdjson::padded_string &json, std::vector<point> &result) {
+    auto doc = parser.iterate(json);
+    if(auto e = doc.get_array().get<std::vector<point>>(result); e) { return false; }
+    // We can also do it like so:
+    //for (ondemand::object coord : doc) {
+    //  result.emplace_back(coord.get<point>());
+    //}
+    // It seems that doing the reflection is slower than doing the manual lookup.
+    // E.g., it is faster if we do result.emplace_back(coord["x"], coord["y"], coord["z"]);
+    return true;
+  }
+};
+BENCHMARK_TEMPLATE(large_random, simdjson_ondemand_static_reflect)->UseManualTime();
+
+
+#endif
 } // namespace large_random
 
 #endif // SIMDJSON_EXCEPTIONS

benchmark/large_random/yyjson.h

@@ -47,18 +47,26 @@ struct yyjson_base {
 
 struct yyjson : yyjson_base {
   bool run(simdjson::padded_string &json, std::vector<point> &result) {
-    return yyjson_base::run(yyjson_read(json.data(), json.size(), 0), result);
+    yyjson_doc *doc = yyjson_read(json.data(), json.size(), 0);
+    bool b = yyjson_base::run(doc, result);
+    yyjson_doc_free(doc);
+    return b;
   }
 };
 BENCHMARK_TEMPLATE(large_random, yyjson)->UseManualTime();
+
 #if SIMDJSON_COMPETITION_ONDEMAND_INSITU
 struct yyjson_insitu : yyjson_base {
   bool run(simdjson::padded_string &json, std::vector<point> &result) {
-    return yyjson_base::run(yyjson_read_opts(json.data(), json.size(), YYJSON_READ_INSITU, 0, 0), result);
+    yyjson_doc *doc = yyjson_read_opts(json.data(), json.size(), YYJSON_READ_INSITU, 0, 0);
+    bool b = yyjson_base::run(doc, result);
+    yyjson_doc_free(doc);
+    return b;
   }
 };
 BENCHMARK_TEMPLATE(large_random, yyjson_insitu)->UseManualTime();
 #endif // SIMDJSON_COMPETITION_ONDEMAND_INSITU
+
 } // namespace large_random
 
 #endif // SIMDJSON_COMPETITION_YYJSON

benchmark/partial_tweets/ondemand.h

@@ -13,7 +13,7 @@ class OnDemand {
 public:
   OnDemand() {
     if(!displayed_implementation) {
-      std::cout << "On Demand implementation: " << builtin_implementation()->name() << std::endl;
+      std::cout << "On-Demand implementation: " << builtin_implementation()->name() << std::endl;
       displayed_implementation = true;
     }
   }

benchmark/partial_tweets/yyjson.h

@@ -62,19 +62,26 @@ struct yyjson_base {
 
 struct yyjson : yyjson_base {
   bool run(simdjson::padded_string &json, std::vector<tweet<std::string_view>> &result) {
-    return yyjson_base::run(yyjson_read(json.data(), json.size(), 0), result);
+    yyjson_doc *doc = yyjson_read(json.data(), json.size(), 0);
+    bool b = yyjson_base::run(doc, result);
+    yyjson_doc_free(doc);
+    return b;
   }
 };
 BENCHMARK_TEMPLATE(partial_tweets, yyjson)->UseManualTime();
+
 #if SIMDJSON_COMPETITION_ONDEMAND_INSITU
 struct yyjson_insitu : yyjson_base {
   bool run(simdjson::padded_string &json, std::vector<tweet<std::string_view>> &result) {
-    return yyjson_base::run(yyjson_read_opts(json.data(), json.size(), YYJSON_READ_INSITU, 0, 0), result);
+    yyjson_doc *doc = yyjson_read_opts(json.data(), json.size(), YYJSON_READ_INSITU, 0, 0);
+    bool b = yyjson_base::run(doc, result);
+    yyjson_doc_free(doc);
+    return b;
   }
 };
 BENCHMARK_TEMPLATE(partial_tweets, yyjson_insitu)->UseManualTime();
 #endif // SIMDJSON_COMPETITION_ONDEMAND_INSITU
+
 } // namespace partial_tweets
 
 #endif // SIMDJSON_COMPETITION_YYJSON
-

benchmark/static_reflect/CMakeLists.txt

@@ -0,0 +1,48 @@
+# Include reflect-cpp
+CPMAddPackage(
+  NAME reflect-cpp
+  GITHUB_REPOSITORY getml/reflect-cpp
+  GIT_TAG v0.17.0
+  EXCLUDE_FROM_ALL YES
+)
+
+option(SIMDJSON_USE_RUST "Build the static_reflect benchmark" OFF)
+
+if(SIMDJSON_USER_RUST)
+  if(NOT WIN32)
+  # We want the check whether Rust is available before trying to build a crate.
+  CPMAddPackage(
+    NAME corrosion
+    GITHUB_REPOSITORY corrosion-rs/corrosion
+    VERSION 0.4.4
+    DOWNLOAD_ONLY ON
+    OPTIONS "Rust_FIND_QUIETLY OFF"
+  )
+  include("${corrosion_SOURCE_DIR}/cmake/FindRust.cmake")
+  endif()
+
+  if(RUST_FOUND)
+    message(STATUS "Rust found: " ${Rust_VERSION} )
+    add_subdirectory("${corrosion_SOURCE_DIR}" "${PROJECT_BINARY_DIR}/_deps/corrosion" EXCLUDE_FROM_ALL)
+    # Important: we want to build in release mode!
+    corrosion_import_crate(MANIFEST_PATH "serde-benchmark/Cargo.toml" NO_LINKER_OVERRIDE PROFILE release)
+  else()
+    message(STATUS "Rust/Cargo is unavailable." )
+    message(STATUS "We will not benchmark serde-benchmark." )
+    if (${CMAKE_SYSTEM_NAME} MATCHES "Darwin")
+      message(STATUS "Under macOS, you may be able to install rust with")
+      message(STATUS "curl https://sh.rustup.rs -sSf | sh")
+    elseif(CMAKE_SYSTEM_NAME STREQUAL "Linux")
+      message(STATUS "Under Linux, you may be able to install rust with a command such as")
+      message(STATUS "apt-get install cargo" )
+      message(STATUS "or" )
+      message(STATUS "curl https://sh.rustup.rs -sSf | sh")
+    endif()
+  endif()
+else(SIMDJSON_USER_RUST)
+  message(STATUS "We will not benchmark serde-benchmark." )
+endif(SIMDJSON_USER_RUST)
+
+# Add the benchmark executable targets
+add_subdirectory(twitter_benchmark)
+add_subdirectory(citm_catalog_benchmark)

benchmark/static_reflect/benchmark_utils/benchmark_helper.h

@@ -0,0 +1,52 @@
+#ifndef BENCHMARK_HELPER_HPP
+#define BENCHMARK_HELPER_HPP
+#include "event_counter.h"
+#include <atomic>
+
+inline event_collector &get_collector() {
+  static event_collector collector;
+  return collector;
+}
+
+template <class function_type>
+event_aggregate bench(const function_type &function, size_t min_repeat = 10,
+                      size_t min_time_ns = 1000000000,
+                      size_t max_repeat = 100000) {
+  event_collector &collector = get_collector();
+  event_aggregate aggregate{};
+  size_t N = min_repeat;
+  if (N == 0) {
+    N = 1;
+  }
+  for (size_t i = 0; i < N; i++) {
+    std::atomic_thread_fence(std::memory_order_acquire);
+    collector.start();
+    function();
+    std::atomic_thread_fence(std::memory_order_release);
+    event_count allocate_count = collector.end();
+    aggregate << allocate_count;
+    if ((i + 1 == N) && (aggregate.total_elapsed_ns() < min_time_ns) &&
+        (N < max_repeat)) {
+      N *= 10;
+    }
+  }
+  return aggregate;
+}
+
+// Source of the 2 functions below:
+// https://github.com/simdutf/simdutf/blob/master/benchmarks/base64/benchmark_base64.cpp
+inline void pretty_print(size_t strings, size_t bytes, std::string name,
+                         event_aggregate agg) {
+  event_collector &collector = get_collector();
+  printf("%-60s : ", name.c_str());
+  printf(" %5.2f MB/s ", bytes * 1000 / agg.elapsed_ns());
+  printf(" %5.2f Ms/s ", strings * 1000 / agg.elapsed_ns());
+  if (collector.has_events()) {
+    printf(" %5.2f GHz ", agg.cycles() / agg.elapsed_ns());
+    printf(" %5.2f c/b ", agg.cycles() / bytes);
+    printf(" %5.2f i/b ", agg.instructions() / bytes);
+    printf(" %5.2f i/c ", agg.instructions() / agg.cycles());
+  }
+  printf("\n");
+}
+#endif

benchmark/static_reflect/citm_catalog_benchmark/CMakeLists.txt

@@ -0,0 +1,14 @@
+add_executable(benchmark_serialization_citm_catalog benchmark_serialization_citm_catalog.cpp)
+
+# Link with Rust benchmarking code if available
+if(TARGET serde-benchmark)
+    message(STATUS "serde-benchmark target was created. Linking CITM catalog benchmark with serde-benchmark.")
+    target_link_libraries(benchmark_serialization_citm_catalog PRIVATE serde-benchmark)
+    target_compile_definitions(benchmark_serialization_citm_catalog PRIVATE SIMDJSON_RUST_VERSION="${Rust_VERSION}")
+endif()
+
+target_link_libraries(benchmark_serialization_citm_catalog PRIVATE simdjson::simdjson nlohmann_json)
+target_link_libraries(benchmark_serialization_citm_catalog PRIVATE reflectcpp)
+target_compile_definitions(benchmark_serialization_citm_catalog PRIVATE SIMDJSON_BENCH_CPP_REFLECT=1)
+
+target_compile_definitions(benchmark_serialization_citm_catalog PRIVATE JSON_FILE="${BENCH_CITM_JSON}")

benchmark/static_reflect/citm_catalog_benchmark/benchmark_serialization_citm_catalog.cpp

@@ -0,0 +1,177 @@
+#include <cassert>
+#include <cstdlib>
+#include <ctime>
+#include <format>
+#include <fstream>
+#include <iostream>
+#include <nlohmann/json.hpp>
+#include <simdjson.h>
+#include <string>
+#include "citm_catalog_data.h"
+#include "nlohmann_citm_catalog_data.h"
+#include "../benchmark_utils/benchmark_helper.h"
+
+#if SIMDJSON_BENCH_CPP_REFLECT
+#include <rfl.hpp>
+#include <rfl/json.hpp>
+void bench_reflect_cpp(CitmCatalog &data) {
+  std::string output = rfl::json::write(data);
+  size_t output_volume = output.size();
+  printf("# output volume: %zu bytes\n", output_volume);
+
+  volatile size_t measured_volume = 0;
+  pretty_print(1, output_volume, "bench_reflect_cpp",
+               bench([&data, &measured_volume, &output_volume]() {
+                 std::string output = rfl::json::write(data);
+                 measured_volume = output.size();
+                 if (measured_volume != output_volume) {
+                   printf("mismatch\n");
+                 }
+               }));
+}
+#endif // SIMDJSON_BENCH_CPP_REFLECT
+
+#ifdef SIMDJSON_RUST_VERSION
+#include "../serde-benchmark/serde_benchmark.h"
+
+void bench_rust(serde_benchmark::CitmCatalog *data) {
+  const char * output = serde_benchmark::str_from_citm(data);
+  size_t output_volume = strlen(output);
+  printf("# output volume: %zu bytes\n", output_volume);
+  volatile size_t measured_volume = 0;
+  pretty_print(1, output_volume, "bench_rust",
+               bench([&data, &measured_volume, &output_volume]() {
+                 const char * output = serde_benchmark::str_from_citm(data);
+                 measured_volume = strlen(output);
+                 if (measured_volume != output_volume) {
+                   printf("mismatch\n");
+                 }
+                 serde_benchmark::free_str(const_cast<char*>(output));
+               }));
+  serde_benchmark::free_str(const_cast<char*>(output));
+}
+#endif // SIMDJSON_RUST_VERSION
+
+void bench_nlohmann(CitmCatalog &data) {
+  std::string output = nlohmann_serialize(data);
+  size_t output_volume = output.size();
+  printf("# output volume: %zu bytes\n", output_volume);
+
+  volatile size_t measured_volume = 0;
+  pretty_print(1, output_volume, "bench_nlohmann",
+               bench([&data, &measured_volume, &output_volume]() {
+                 std::string output = nlohmann_serialize(data);
+                 measured_volume = output.size();
+                 if (measured_volume != output_volume) {
+                   printf("mismatch\n");
+                 }
+               }));
+}
+
+void bench_simdjson_static_reflection(CitmCatalog &data) {
+  simdjson::builder::string_builder sb;
+  simdjson::builder::append(sb, data);
+  std::string_view p;
+  if(sb.view().get(p)) {
+    std::cerr << "Error!" << std::endl;
+  }
+  size_t output_volume = p.size();
+  sb.clear();
+  printf("# output volume: %zu bytes\n", output_volume);
+
+  volatile size_t measured_volume = 0;
+  pretty_print(sizeof(data), output_volume, "bench_simdjson_static_reflection",
+               bench([&data, &measured_volume, &output_volume, &sb]() {
+                 sb.clear();
+                 simdjson::builder::append(sb, data);
+                 std::string_view p;
+                 if(sb.view().get(p)) {
+                   std::cerr << "Error!" << std::endl;
+                 }
+                 measured_volume = sb.size();
+                 if (measured_volume != output_volume) {
+                   printf("mismatch\n");
+                 }
+               }));
+}
+
+std::string read_file(const std::string &file_path, size_t read_size = 65536) {
+  std::ifstream stream(file_path, std::ios::binary);
+  if(!stream) {
+    std::cerr << "Could not open file '" << file_path << "'" << std::endl;
+    exit(EXIT_FAILURE);
+  }
+  stream.exceptions(std::ios_base::badbit);
+  std::string out;
+  std::string buf(read_size, '\0');
+  while (stream.read(&buf[0], read_size)) {
+    out.append(buf, 0, size_t(stream.gcount()));
+  }
+  out.append(buf, 0, size_t(stream.gcount()));
+  return out;
+}
+
+// Function to check if benchmark name contains filter substring
+bool matches_filter(const std::string& benchmark_name, const std::string& filter) {
+  return filter.empty() || benchmark_name.find(filter) != std::string::npos;
+}
+
+int main(int argc, char* argv[]) {
+  std::string filter;
+
+  // Parse command-line arguments
+  for (int i = 1; i < argc; ++i) {
+      if (strcmp(argv[i], "-f") == 0 || strcmp(argv[i], "--filter") == 0) {
+          if (i + 1 < argc) {
+              filter = argv[++i];
+          } else {
+              std::cerr << "Error: -f/--filter requires an argument" << std::endl;
+              return EXIT_FAILURE;
+          }
+      }
+  }
+  // Testing correctness of round-trip (serialization + deserialization)
+  std::string json_str = read_file(JSON_FILE);
+
+  // Loading up the data into a structure.
+  simdjson::ondemand::parser parser;
+  simdjson::ondemand::document doc;
+  if(parser.iterate(simdjson::pad(json_str)).get(doc)) {
+    std::cerr << "Error loading the document!" << std::endl;
+    return EXIT_FAILURE;
+  }
+  CitmCatalog my_struct;
+  if(doc.get<CitmCatalog>().get(my_struct)) {
+    std::cerr << "Error loading CitmCatalog!" << std::endl;
+    return EXIT_FAILURE;
+  }
+
+  // Benchmarking the serialization
+  if (matches_filter("nlohmann", filter)) {
+    bench_nlohmann(my_struct);
+  }
+  if (matches_filter("simdjson_static_reflection", filter)) {
+    bench_simdjson_static_reflection(my_struct);
+  }
+#ifdef SIMDJSON_RUST_VERSION
+  if (matches_filter("rust", filter)) {
+    printf("# WARNING: The Rust benchmark may not be directly comparable since it does not use an equivalent data structure.\n");
+    // Create a Rust-compatible CitmCatalog structure from the JSON string
+    serde_benchmark::CitmCatalog* rust_data =
+      serde_benchmark::citm_from_str(json_str.c_str(), json_str.size());
+
+    if (rust_data == nullptr) {
+      printf("# Failed to initialize Rust data structure\n");
+    } else {
+      bench_rust(rust_data);
+      serde_benchmark::free_citm(rust_data);
+    }
+  }
+#endif
+#if SIMDJSON_BENCH_CPP_REFLECT
+  if (matches_filter("reflect_cpp", filter)) {
+    bench_reflect_cpp(my_struct);
+  }
+#endif
+  return EXIT_SUCCESS;
+}

benchmark/static_reflect/citm_catalog_benchmark/citm_catalog_data.h

@@ -0,0 +1,82 @@
+#ifndef CITM_CATALOG_DATA_H
+#define CITM_CATALOG_DATA_H
+
+#include <string>
+#include <vector>
+#include <map>
+
+struct Area {
+  int64_t id;
+  std::string name;
+  int64_t parent;
+  std::vector<int64_t> childAreas;
+  bool operator==(const Area &other) const = default;
+};
+
+struct AudienceSubCategory {
+  int64_t id;
+  std::string name;
+  int64_t parent;
+  bool operator==(const AudienceSubCategory &other) const = default;
+};
+
+struct Event {
+  int64_t id;
+  std::string name;
+  std::string description;
+  int64_t subTopic;
+  int64_t topic;
+  std::vector<int64_t> audience;
+  bool operator==(const Event &other) const = default;
+};
+
+struct Performance {
+  int64_t id;
+  std::string name;
+  int64_t event;
+  std::string start;
+  int64_t venueCode;
+  bool operator==(const Performance &other) const = default;
+};
+
+struct SeatCategory {
+  int64_t id;
+  std::string name;
+  std::vector<int64_t> areas;
+  bool operator==(const SeatCategory &other) const = default;
+};
+
+struct SubTopic {
+  int64_t id;
+  std::string name;
+  int64_t parent;
+  bool operator==(const SubTopic &other) const = default;
+};
+
+struct Topic {
+  int64_t id;
+  std::string name;
+  bool operator==(const Topic &other) const = default;
+};
+
+struct Venue {
+  int64_t id;
+  std::string name;
+  int64_t address;
+  bool operator==(const Venue &other) const = default;
+};
+
+struct CitmCatalog {
+  std::map<std::string, Area> areas;
+  std::map<std::string, AudienceSubCategory> audienceSubCategory;
+  std::map<std::string, Event> events;
+  std::map<std::string, Performance> performances;
+  std::map<std::string, SeatCategory> seatCategory;
+  std::map<std::string, SubTopic> subTopic;
+  std::map<std::string, Topic> topic;
+  std::map<std::string, Venue> venue;
+
+  bool operator==(const CitmCatalog &other) const = default;
+};
+
+#endif

benchmark/static_reflect/citm_catalog_benchmark/nlohmann_citm_catalog_data.h

@@ -0,0 +1,171 @@
+// nlohmann_citm_catalog_data.h
+#ifndef NLOHMANN_CITM_CATALOG_DATA_H
+#define NLOHMANN_CITM_CATALOG_DATA_H
+
+#include "citm_catalog_data.h"
+#include <nlohmann/json.hpp>
+#include <string>
+
+using json = nlohmann::json;
+
+// ---- Area ----
+inline void to_json(json &j, const Area &a) {
+    j = json{
+      {"id", a.id},
+      {"name", a.name},
+      {"parent", a.parent},
+      {"childAreas", a.childAreas}
+    };
+}
+inline void from_json(const json &j, Area &a) {
+    j.at("id").get_to(a.id);
+    j.at("name").get_to(a.name);
+    j.at("parent").get_to(a.parent);
+    j.at("childAreas").get_to(a.childAreas);
+}
+
+// ---- AudienceSubCategory ----
+inline void to_json(json &j, const AudienceSubCategory &asc) {
+    j = json{
+      {"id", asc.id},
+      {"name", asc.name},
+      {"parent", asc.parent}
+    };
+}
+inline void from_json(const json &j, AudienceSubCategory &asc) {
+    j.at("id").get_to(asc.id);
+    j.at("name").get_to(asc.name);
+    j.at("parent").get_to(asc.parent);
+}
+
+// ---- Event ----
+inline void to_json(json &j, const Event &e) {
+    j = json{
+      {"id", e.id},
+      {"name", e.name},
+      {"description", e.description},
+      {"subTopic", e.subTopic},
+      {"topic", e.topic},
+      {"audience", e.audience}
+    };
+}
+inline void from_json(const json &j, Event &e) {
+    j.at("id").get_to(e.id);
+    j.at("name").get_to(e.name);
+    j.at("description").get_to(e.description);
+    j.at("subTopic").get_to(e.subTopic);
+    j.at("topic").get_to(e.topic);
+    j.at("audience").get_to(e.audience);
+}
+
+// ---- Performance ----
+inline void to_json(json &j, const Performance &p) {
+    j = json{
+      {"id", p.id},
+      {"name", p.name},
+      {"event", p.event},
+      {"start", p.start},
+      {"venueCode", p.venueCode}
+    };
+}
+inline void from_json(const json &j, Performance &p) {
+    j.at("id").get_to(p.id);
+    j.at("name").get_to(p.name);
+    j.at("event").get_to(p.event);
+    j.at("start").get_to(p.start);
+    j.at("venueCode").get_to(p.venueCode);
+}
+
+// ---- SeatCategory ----
+inline void to_json(json &j, const SeatCategory &sc) {
+    j = json{
+      {"id", sc.id},
+      {"name", sc.name},
+      {"areas", sc.areas}
+    };
+}
+inline void from_json(const json &j, SeatCategory &sc) {
+    j.at("id").get_to(sc.id);
+    j.at("name").get_to(sc.name);
+    j.at("areas").get_to(sc.areas);
+}
+
+// ---- SubTopic ----
+inline void to_json(json &j, const SubTopic &st) {
+    j = json{
+      {"id", st.id},
+      {"name", st.name},
+      {"parent", st.parent}
+    };
+}
+inline void from_json(const json &j, SubTopic &st) {
+    j.at("id").get_to(st.id);
+    j.at("name").get_to(st.name);
+    j.at("parent").get_to(st.parent);
+}
+
+// ---- Topic ----
+inline void to_json(json &j, const Topic &t) {
+    j = json{
+      {"id", t.id},
+      {"name", t.name}
+    };
+}
+inline void from_json(const json &j, Topic &t) {
+    j.at("id").get_to(t.id);
+    j.at("name").get_to(t.name);
+}
+
+// ---- Venue ----
+inline void to_json(json &j, const Venue &v) {
+    j = json{
+      {"id", v.id},
+      {"name", v.name},
+      {"address", v.address}
+    };
+}
+inline void from_json(const json &j, Venue &v) {
+    j.at("id").get_to(v.id);
+    j.at("name").get_to(v.name);
+    j.at("address").get_to(v.address);
+}
+
+// ---- CitmCatalog ----
+inline void to_json(json &j, const CitmCatalog &c) {
+    j = json{
+      {"areas", c.areas},
+      {"audienceSubCategory", c.audienceSubCategory},
+      {"events", c.events},
+      {"performances", c.performances},
+      {"seatCategory", c.seatCategory},
+      {"subTopic", c.subTopic},
+      {"topic", c.topic},
+      {"venue", c.venue}
+    };
+}
+inline void from_json(const json &j, CitmCatalog &c) {
+    j.at("areas").get_to(c.areas);
+    j.at("audienceSubCategory").get_to(c.audienceSubCategory);
+    j.at("events").get_to(c.events);
+    j.at("performances").get_to(c.performances);
+    j.at("seatCategory").get_to(c.seatCategory);
+    j.at("subTopic").get_to(c.subTopic);
+    j.at("topic").get_to(c.topic);
+    j.at("venue").get_to(c.venue);
+}
+
+// Optional convenience functions for benchmarking
+inline std::string nlohmann_serialize(const CitmCatalog &catalog) {
+    json j = catalog;
+    return j.dump();
+}
+inline bool nlohmann_deserialize(const std::string &json_in, CitmCatalog &catalog) {
+    try {
+        catalog = json::parse(json_in);
+        return false; // success
+    } catch(...) {
+        return true;  // failure
+    }
+}
+
+#endif // NLOHMANN_CITM_CATALOG_DATA_H

benchmark/static_reflect/serde-benchmark/Cargo.lock

@@ -0,0 +1,103 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 3
+
+[[package]]
+name = "itoa"
+version = "1.0.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "49f1f14873335454500d59611f1cf4a4b0f786f9ac11f4312a78e4cf2566695b"
+
+[[package]]
+name = "libc"
+version = "0.2.158"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d8adc4bb1803a324070e64a98ae98f38934d91957a99cfb3a43dcbc01bc56439"
+
+[[package]]
+name = "memchr"
+version = "2.7.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "78ca9ab1a0babb1e7d5695e3530886289c18cf2f87ec19a575a0abdce112e3a3"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.86"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5e719e8df665df0d1c8fbfd238015744736151d4445ec0836b8e628aae103b77"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.37"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b5b9d34b8991d19d98081b46eacdd8eb58c6f2b201139f7c5f643cc155a633af"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "ryu"
+version = "1.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f3cb5ba0dc43242ce17de99c180e96db90b235b8a9fdc9543c96d2209116bd9f"
+
+[[package]]
+name = "serde"
+version = "1.0.209"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "99fce0ffe7310761ca6bf9faf5115afbc19688edd00171d81b1bb1b116c63e09"
+dependencies = [
+ "serde_derive",
+]
+
+[[package]]
+name = "serde-benchmark"
+version = "0.1.0"
+dependencies = [
+ "libc",
+ "serde",
+ "serde_json",
+]
+
+[[package]]
+name = "serde_derive"
+version = "1.0.209"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a5831b979fd7b5439637af1752d535ff49f4860c0f341d1baeb6faf0f4242170"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "serde_json"
+version = "1.0.127"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8043c06d9f82bd7271361ed64f415fe5e12a77fdb52e573e7f06a516dea329ad"
+dependencies = [
+ "itoa",
+ "memchr",
+ "ryu",
+ "serde",
+]
+
+[[package]]
+name = "syn"
+version = "2.0.76"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "578e081a14e0cefc3279b0472138c513f37b41a08d5a3cca9b6e4e8ceb6cd525"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3354b9ac3fae1ff6755cb6db53683adb661634f67557942dea4facebec0fee4b"

benchmark/static_reflect/serde-benchmark/Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+name = "serde-benchmark"
+version = "0.1.0"
+
+[lib]
+path = "lib.rs"
+crate-type = ["cdylib"]
+
+[dependencies]
+serde = { version = "1.0", features = ["derive"] }
+libc = "0.2"
+serde_json = "1.0"
+
+[profile.release]
+opt-level = 3
+debug = false
+lto = true

benchmark/static_reflect/serde-benchmark/README.md

@@ -0,0 +1,18 @@
+## Rust Serde FFI
+
+This folder includes FFI bindings for rust/serde.
+
+### Links
+
+- https://github.com/eqrion/cbindgen/blob/master/docs.md
+- https://gist.github.com/zbraniecki/b251714d77ffebbc73c03447f2b2c69f
+- https://michael-f-bryan.github.io/rust-ffi-guide/setting_up.html
+
+### Building
+
+- Generating cbindgen output
+  - Install dependencies with `brew install cbindgen` or `apt-get install cbindgen` or `cargo install cbindgen` or the equivalent: we used `cargo install --version 0.23.0 cbindgen`.
+  - Go to the directory where this README.md file is located
+  - Generate with `cbindgen --config cbindgen.toml --crate serde-benchmark --output serde_benchmark.h`
+- Building
+  - Run with `cargo build --release`

benchmark/static_reflect/serde-benchmark/cbindgen.toml

@@ -0,0 +1,12 @@
+autogen_warning = "/* Warning, this file is autogenerated by cbindgen. Don't modify this manually. */"
+include_version = true
+braces = "SameLine"
+line_length = 100
+tab_width = 2
+language = "C++"
+namespaces = ["serde_benchmark"]
+include_guard = "serde_benchmark_ffi_h"
+
+[parse]
+parse_deps = true
+include = ["serde_json", "serde"]

benchmark/static_reflect/serde-benchmark/lib.rs

@@ -0,0 +1,482 @@
+extern crate serde;
+extern crate serde_json;
+extern crate libc;
+
+use libc::{c_char, size_t};
+use serde::{Serialize, Deserialize};
+use std::{collections::HashMap, ffi::CString, ptr, slice};
+use serde::de::{self, Deserializer};
+/******************************************************/
+/******************************************************/
+/**
+ * Warning: the C++ code may not generate the same JSON.
+ */
+ /******************************************************/
+ /******************************************************/
+
+// This has no equivalent in C++:
+#[derive(Serialize, Deserialize)]
+pub struct Metadata {
+    result_type: String,
+    iso_language_code: String,
+}
+
+#[derive(Serialize, Deserialize)]
+pub struct User {
+    id: i64,
+    id_str: String,
+    name: String,
+    screen_name: String,
+    location: String,
+    description: String,
+    // C++ does not have those:
+    // url: Option<String>,
+    //protected: bool,
+    //listed_count: i64,
+    //created_at: String,
+    //favourites_count: i64,
+    //utc_offset: Option<i64>,
+    //time_zone: Option<String>,
+    //geo_enabled: bool,
+    verified: bool,
+    followers_count: i64,
+    friends_count: i64,
+    statuses_count: i64,
+    // C++ does not have those:
+    //lang: String,
+    //profile_background_color: String,
+    //profile_background_image_url: String,
+    //profile_background_image_url_https: String,
+    //profile_background_tile: bool,
+    //profile_image_url: String,
+    //profile_image_url_https: String,
+    //profile_banner_url: Option<String>,
+    //profile_link_color: String,
+    //profile_sidebar_border_color: String,
+    //profile_sidebar_fill_color: String,
+    //profile_text_color: String,
+    //profile_use_background_image: bool,
+    //default_profile: bool,
+    //default_profile_image: bool,
+    //following: bool,
+    //follow_request_sent: bool,
+    //notifications: bool,
+}
+
+#[derive(Serialize, Deserialize)]
+pub struct Hashtag {
+    text: String,
+
+    // C++ has those but D. Lemire does not know what they are, they don't appear in the JSON:
+    // int64_t indices_start;
+    // int64_t indices_end;
+}
+
+#[derive(Serialize, Deserialize)]
+pub struct Url {
+    url: String,
+    expanded_url: String,
+    display_url: String,
+    // C++ has those but D. Lemire does not know what they are, they don't appear in the JSON:
+    // int64_t indices_start;
+    // int64_t indices_end;
+}
+
+#[derive(Serialize, Deserialize)]
+pub struct UserMention {
+    id: i64,
+    name: String,
+    screen_name: String,
+    // Not in the C++ equivalent:
+    //id_str: String,
+    //indices: Vec<i64>,
+    // C++ has those but D. Lemire does not know what they are, they don't appear in the JSON:
+    // int64_t indices_start;
+    // int64_t indices_end;
+}
+
+#[derive(Serialize, Deserialize)]
+pub struct Entities {
+    hashtags: Vec<Hashtag>,
+    urls: Vec<Url>,
+    user_mentions: Vec<UserMention>,
+}
+
+#[derive(Serialize, Deserialize)]
+pub struct Status {
+    created_at: String,
+    id: i64,
+    text: String,
+    user: User,
+    entities: Entities,
+    retweet_count: i64,
+    favorite_count: i64,
+    favorited: bool,
+    retweeted: bool,
+    // None of these are in the C++ equivalent:
+    /*
+    metadata: Metadata,
+    id_str: String,
+    source: String,
+    truncated: bool,
+    in_reply_to_status_id: Option<i64>,
+    in_reply_to_status_id_str: Option<String>,
+    in_reply_to_user_id: Option<i64>,
+    in_reply_to_user_id_str: Option<String>,
+    in_reply_to_screen_name: Option<String>,
+    geo: Option<String>,
+    coordinates: Option<String>,
+    place: Option<String>,
+    contributors: Option<String>,
+    lang: String,
+    */
+}
+
+#[derive(Serialize, Deserialize)]
+pub struct TwitterData {
+    statuses: Vec<Status>,
+}
+
+#[no_mangle]
+pub unsafe extern "C" fn  twitter_from_str(raw_input: *const c_char, raw_input_length: size_t) -> *mut TwitterData {
+  let input = std::str::from_utf8_unchecked(slice::from_raw_parts(raw_input as *const u8, raw_input_length));
+  match serde_json::from_str(&input) {
+    Ok(result) => Box::into_raw(Box::new(result)),
+    Err(_) => std::ptr::null_mut(),
+  }
+}
+
+#[no_mangle]
+pub unsafe extern "C" fn str_from_twitter(raw: *mut TwitterData) -> *const c_char {
+  let twitter_thing = { &*raw };
+  let serialized = serde_json::to_string(&twitter_thing).unwrap();
+  return std::ffi::CString::new(serialized.as_str()).unwrap().into_raw()
+}
+
+
+#[no_mangle]
+pub unsafe extern "C" fn free_twitter(raw: *mut TwitterData) {
+  if raw.is_null() {
+    return;
+  }
+
+  drop(Box::from_raw(raw))
+}
+
+
+#[no_mangle]
+pub unsafe extern fn free_string(ptr: *const c_char) {
+    let _ = std::ffi::CString::from_raw(ptr as *mut _);
+}
+
+// Functions associated with the CitmCatalog benchmark
+
+#[derive(Serialize, Deserialize)]
+pub struct Area {
+    pub id: i64,
+    pub name: Option<String>,  // Changed to Option
+    pub parent: i64,
+    #[serde(rename = "childAreas")]
+    pub child_areas: Vec<i64>,
+}
+
+#[derive(Serialize, Deserialize)]
+pub struct AudienceSubCategory {
+    pub id: i64,
+    pub name: Option<String>,  // Changed to Option
+    pub parent: i64,
+}
+
+#[derive(Serialize, Deserialize, Debug)]
+pub struct Event {
+    #[serde(default)]
+    pub description: Option<String>,
+    pub id: i64,
+    #[serde(default)]
+    pub logo: Option<String>,
+    #[serde(default)]
+    pub name: Option<String>,
+    #[serde(default)]
+    pub subTopicIds: Vec<i64>,
+    #[serde(default)]
+    pub subjectCode: Option<String>,
+    #[serde(default)]
+    pub subtitle: Option<String>,
+    #[serde(default)]
+    pub topicIds: Vec<i64>,
+    // Add a catch-all for any other fields
+    #[serde(flatten)]
+    pub extra: HashMap<String, serde_json::Value>,
+}
+
+#[derive(Serialize, Deserialize, Debug)]
+pub struct Performance {
+    #[serde(default)]
+    pub id: i64,
+
+    #[serde(default)]
+    pub name: Option<String>,
+
+    #[serde(default)]
+    pub event: i64,
+
+    // This is the key fix - accept any JSON value type for timestamps
+    // This allows both string dates and integer timestamps (line 3511)
+    #[serde(default)]
+    pub start: serde_json::Value,
+
+    #[serde(rename = "venueCode")]
+    pub venue_code: String,
+
+    // Add a catch-all for any other fields
+    #[serde(flatten)]
+    pub extra: HashMap<String, serde_json::Value>,
+}
+
+#[derive(Serialize, Deserialize)]
+pub struct SeatCategory {
+    pub id: i64,
+    pub name: Option<String>,  // Changed to Option
+    pub areas: Vec<i64>,
+}
+
+#[derive(Serialize, Deserialize)]
+pub struct SubTopic {
+    pub id: i64,
+    pub name: Option<String>,  // Changed to Option
+    pub parent: i64,
+}
+
+#[derive(Serialize, Deserialize)]
+pub struct Topic {
+    pub id: i64,
+    pub name: Option<String>,  // Changed to Option
+}
+
+#[derive(Serialize, Deserialize)]
+pub struct Venue {
+    pub id: i64,
+    pub name: Option<String>,  // Changed to Option
+    pub address: i64,
+}
+
+// Custom deserializers
+fn deserialize_string_to_area<'de, D>(deserializer: D) -> Result<HashMap<String, Area>, D::Error>
+where D: Deserializer<'de> {
+    let string_map: HashMap<String, String> = HashMap::deserialize(deserializer)?;
+    let mut result = HashMap::new();
+
+    for (id, name) in string_map {
+        let id_num = id.parse::<i64>().unwrap_or(0);
+        result.insert(id.clone(), Area {
+            id: id_num,
+            name: Some(name),
+            parent: 0,
+            child_areas: Vec::new(),
+        });
+    }
+
+    Ok(result)
+}
+
+fn deserialize_string_to_audience_subcategory<'de, D>(deserializer: D) -> Result<HashMap<String, AudienceSubCategory>, D::Error>
+where D: Deserializer<'de> {
+    let string_map: HashMap<String, String> = HashMap::deserialize(deserializer)?;
+    let mut result = HashMap::new();
+
+    for (id, name) in string_map {
+        let id_num = id.parse::<i64>().unwrap_or(0);
+        result.insert(id.clone(), AudienceSubCategory {
+            id: id_num,
+            name: Some(name),
+            parent: 0,
+        });
+    }
+
+    Ok(result)
+}
+
+fn deserialize_string_to_seat_category<'de, D>(deserializer: D) -> Result<HashMap<String, SeatCategory>, D::Error>
+where D: Deserializer<'de> {
+    let string_map: HashMap<String, String> = HashMap::deserialize(deserializer)?;
+    let mut result = HashMap::new();
+
+    for (id, name) in string_map {
+        let id_num = id.parse::<i64>().unwrap_or(0);
+        result.insert(id.clone(), SeatCategory {
+            id: id_num,
+            name: Some(name),
+            areas: Vec::new(),
+        });
+    }
+
+    Ok(result)
+}
+
+fn deserialize_string_to_subtopic<'de, D>(deserializer: D) -> Result<HashMap<String, SubTopic>, D::Error>
+where D: Deserializer<'de> {
+    let string_map: HashMap<String, String> = HashMap::deserialize(deserializer)?;
+    let mut result = HashMap::new();
+
+    for (id, name) in string_map {
+        let id_num = id.parse::<i64>().unwrap_or(0);
+        result.insert(id.clone(), SubTopic {
+            id: id_num,
+            name: Some(name),
+            parent: 0,
+        });
+    }
+
+    Ok(result)
+}
+
+fn deserialize_string_to_topic<'de, D>(deserializer: D) -> Result<HashMap<String, Topic>, D::Error>
+where D: Deserializer<'de> {
+    let string_map: HashMap<String, String> = HashMap::deserialize(deserializer)?;
+    let mut result = HashMap::new();
+
+    for (id, name) in string_map {
+        let id_num = id.parse::<i64>().unwrap_or(0);
+        result.insert(id.clone(), Topic {
+            id: id_num,
+            name: Some(name),
+        });
+    }
+
+    Ok(result)
+}
+
+fn deserialize_string_to_venue<'de, D>(deserializer: D) -> Result<HashMap<String, Venue>, D::Error>
+where D: Deserializer<'de> {
+    let string_map: HashMap<String, String> = HashMap::deserialize(deserializer)?;
+    let mut result = HashMap::new();
+
+    for (id, name) in string_map {
+        result.insert(id.clone(), Venue {
+            id: 0,
+            name: Some(name),
+            address: 0,
+        });
+    }
+
+    Ok(result)
+}
+
+#[derive(Serialize, Deserialize, Debug)]
+pub struct CitmCatalog {
+    #[serde(rename = "areaNames")]
+    pub area_names: HashMap<String, String>,
+
+    #[serde(rename = "audienceSubCategoryNames")]
+    pub audience_subcategory_names: HashMap<String, String>,
+
+    #[serde(default)]
+    #[serde(rename = "blockNames")]
+    pub block_names: HashMap<String, String>,
+
+    pub events: HashMap<String, Event>,
+
+    #[serde(default)]
+    pub performances: Vec<Performance>,
+
+    #[serde(rename = "seatCategoryNames")]
+    pub seat_category_names: HashMap<String, String>,
+
+    #[serde(rename = "subTopicNames")]
+    pub subtopic_names: HashMap<String, String>,
+
+    #[serde(default)]
+    #[serde(rename = "subjectNames")]
+    pub subject_names: HashMap<String, String>,
+
+    #[serde(rename = "topicNames")]
+    pub topic_names: HashMap<String, String>,
+
+    #[serde(rename = "topicSubTopics")]
+    pub topic_subtopics: HashMap<String, Vec<i64>>,
+
+    #[serde(rename = "venueNames")]
+    pub venue_names: HashMap<String, String>,
+
+    // Catch-all for other fields
+    #[serde(flatten)]
+    pub extra: HashMap<String, serde_json::Value>,
+}
+
+/// Creates a CitmCatalog from a JSON string (UTF-8 encoded).
+#[no_mangle]
+pub unsafe extern "C" fn citm_from_str(
+    raw_input: *const c_char,
+    raw_input_length: usize
+) -> *mut CitmCatalog {
+    if raw_input.is_null() {
+        eprintln!("Error: Input pointer is null");
+        return ptr::null_mut();
+    }
+
+    // Convert the raw pointer + length into a Rust slice
+    let bytes = slice::from_raw_parts(raw_input as *const u8, raw_input_length);
+    let input_str = match std::str::from_utf8(bytes) {
+        Ok(s) => s,
+        Err(e) => {
+            eprintln!("Error: Invalid UTF-8 string: {}", e);
+            return ptr::null_mut();
+        }
+    };
+
+    // Try deserializing the input string into CitmCatalog
+    match serde_json::from_str::<CitmCatalog>(input_str) {
+        Ok(catalog) => Box::into_raw(Box::new(catalog)),
+        Err(e) => {
+            eprintln!("Error deserializing JSON: {}", e);
+            eprintln!("JSON snippet (first 200 chars): {:.200}...", input_str);
+            ptr::null_mut()
+        }
+    }
+}
+
+/// Serializes a CitmCatalog into a JSON string (UTF-8).
+#[no_mangle]
+pub unsafe extern "C" fn str_from_citm(raw_catalog: *mut CitmCatalog) -> *mut c_char {
+    if raw_catalog.is_null() {
+        eprintln!("Error: Catalog pointer is null");
+        return ptr::null_mut();
+    }
+
+    // Fix: Actually serialize the catalog
+    let catalog = &*raw_catalog;
+
+    match serde_json::to_string(catalog) {
+        Ok(serialized) => {
+            match CString::new(serialized) {
+                Ok(cstr) => cstr.into_raw(),
+                Err(e) => {
+                    eprintln!("Error creating CString: {}", e);
+                    ptr::null_mut()
+                }
+            }
+        },
+        Err(e) => {
+            eprintln!("Error serializing catalog to JSON: {}", e);
+            ptr::null_mut()
+        }
+    }
+}
+
+/// Frees the CitmCatalog pointer.
+#[no_mangle]
+pub unsafe extern "C" fn free_citm(raw_catalog: *mut CitmCatalog) {
+    if !raw_catalog.is_null() {
+        drop(Box::from_raw(raw_catalog));
+    }
+}
+
+#[no_mangle]
+pub extern "C" fn free_str(ptr: *mut c_char) {
+    if !ptr.is_null() {
+        unsafe {
+            // Convert back into a CString, which automatically frees the memory
+            let _ = CString::from_raw(ptr);
+        }
+    }
+}

benchmark/static_reflect/serde-benchmark/serde_benchmark.h

@@ -0,0 +1,45 @@
+#ifndef serde_benchmark_ffi_h
+#define serde_benchmark_ffi_h
+
+/* Generated with cbindgen:0.28.0 */
+
+/* Warning, this file is autogenerated by cbindgen. Don't modify this manually. */
+
+#include <cstdarg>
+#include <cstdint>
+#include <cstdlib>
+#include <ostream>
+#include <new>
+
+namespace serde_benchmark {
+
+struct CitmCatalog;
+
+struct TwitterData;
+
+extern "C" {
+
+TwitterData *twitter_from_str(const char *raw_input, size_t raw_input_length);
+
+const char *str_from_twitter(TwitterData *raw);
+
+void free_twitter(TwitterData *raw);
+
+void free_string(const char *ptr);
+
+/// Creates a CitmCatalog from a JSON string (UTF-8 encoded).
+CitmCatalog *citm_from_str(const char *raw_input, uintptr_t raw_input_length);
+
+/// Serializes a CitmCatalog into a JSON string (UTF-8).
+char *str_from_citm(CitmCatalog *raw_catalog);
+
+/// Frees the CitmCatalog pointer.
+void free_citm(CitmCatalog *raw_catalog);
+
+void free_str(char *ptr);
+
+}  // extern "C"
+
+}  // namespace serde_benchmark
+
+#endif  // serde_benchmark_ffi_h

benchmark/static_reflect/twitter_benchmark/CMakeLists.txt

@@ -0,0 +1,14 @@
+
+# Add executable targets
+add_executable(benchmark_serialization_twitter benchmark_serialization_twitter.cpp)
+
+ if(TARGET serde-benchmark)
+    message(STATUS "serde-benchmark target was created. Linking benchmarks and serde-benchmark.")
+    target_link_libraries(benchmark_serialization_twitter PRIVATE serde-benchmark)
+    target_compile_definitions(benchmark_serialization_twitter PRIVATE SIMDJSON_RUST_VERSION="${Rust_VERSION}")
+endif()
+target_link_libraries(benchmark_serialization_twitter PRIVATE simdjson::simdjson nlohmann_json)
+target_link_libraries(benchmark_serialization_twitter PRIVATE reflectcpp)
+target_compile_definitions(benchmark_serialization_twitter PRIVATE SIMDJSON_BENCH_CPP_REFLECT=1)
+
+target_compile_definitions(benchmark_serialization_twitter PRIVATE JSON_FILE="${EXAMPLE_JSON}")

benchmark/static_reflect/twitter_benchmark/benchmark_serialization_twitter.cpp

@@ -0,0 +1,168 @@
+#include <cassert>
+#include <cstdlib>
+#include <ctime>
+#include <format>
+#include <fstream>
+#include <iostream>
+#include <nlohmann/json.hpp>
+#include <simdjson.h>
+#include <string>
+#include "twitter_data.h"
+#include "nlohmann_twitter_data.h"
+#include "../benchmark_utils/benchmark_helper.h"
+#if SIMDJSON_BENCH_CPP_REFLECT
+#include <rfl.hpp>
+#include <rfl/json.hpp>
+void bench_reflect_cpp(TwitterData &data) {
+  std::string output = rfl::json::write(data);
+  size_t output_volume = output.size();
+  printf("# output volume: %zu bytes\n", output_volume);
+
+  volatile size_t measured_volume = 0;
+  pretty_print(1, output_volume, "bench_reflect_cpp",
+               bench([&data, &measured_volume, &output_volume]() {
+                 std::string output = rfl::json::write(data);
+                 measured_volume = output.size();
+                 if (measured_volume != output_volume) {
+                   printf("mismatch\n");
+                 }
+               }));
+}
+#endif // SIMDJSON_BENCH_CPP_REFLECT
+
+#ifdef SIMDJSON_RUST_VERSION
+#include "../serde-benchmark/serde_benchmark.h"
+
+
+void bench_rust(serde_benchmark::TwitterData *data) {
+  const char * output = serde_benchmark::str_from_twitter(data);
+  size_t output_volume = strlen(output);
+  printf("# output volume: %zu bytes\n", output_volume);
+  volatile size_t measured_volume = 0;
+  pretty_print(1, output_volume, "bench_rust",
+               bench([&data, &measured_volume, &output_volume]() {
+                 const char * output = serde_benchmark::str_from_twitter(data);
+                 serde_benchmark::free_string(output);
+               }));
+}
+#endif
+
+template <class T> void bench_simdjson_static_reflection(T &data) {
+  simdjson::builder::string_builder sb;
+  simdjson::builder::append(sb, data);
+  std::string_view p;
+  if(sb.view().get(p)) {
+    std::cerr << "Error!" << std::endl;
+  }
+  size_t output_volume = p.size();
+  sb.clear();
+  printf("# output volume: %zu bytes\n", output_volume);
+
+  volatile size_t measured_volume = 0;
+  pretty_print(sizeof(data), output_volume, "bench_simdjson_static_reflection",
+               bench([&data, &measured_volume, &output_volume, &sb]() {
+                 sb.clear();
+                 simdjson::builder::append(sb, data);
+                 std::string_view p;
+                 if(sb.view().get(p)) {
+                   std::cerr << "Error!" << std::endl;
+                 }
+                 measured_volume = sb.size();
+                 if (measured_volume != output_volume) {
+                   printf("mismatch\n");
+                 }
+               }));
+}
+
+void bench_nlohmann(TwitterData &data) {
+  std::string output = nlohmann_serialize(data);
+  size_t output_volume = output.size();
+  printf("# output volume: %zu bytes\n", output_volume);
+
+  volatile size_t measured_volume = 0;
+  pretty_print(1, output_volume, "bench_nlohmann",
+               bench([&data, &measured_volume, &output_volume]() {
+                 std::string output = nlohmann_serialize(data);
+                 measured_volume = output.size();
+                 if (measured_volume != output_volume) {
+                   printf("mismatch\n");
+                 }
+               }));
+}
+
+size_t WriteCallback(void *contents, size_t size, size_t nmemb, void *userp) {
+  ((std::string *)userp)->append((char *)contents, size * nmemb);
+  return size * nmemb;
+}
+
+std::string read_file(std::string filename) {
+  printf("# Reading file %s\n", filename.c_str());
+  constexpr size_t read_size = 4096;
+  auto stream = std::ifstream(filename.c_str());
+  stream.exceptions(std::ios_base::badbit);
+  std::string out;
+  std::string buf(read_size, '\0');
+  while (stream.read(&buf[0], read_size)) {
+    out.append(buf, 0, size_t(stream.gcount()));
+  }
+  out.append(buf, 0, size_t(stream.gcount()));
+  return out;
+}
+
+// Function to check if benchmark name contains filter substring
+bool matches_filter(const std::string& benchmark_name, const std::string& filter) {
+  return filter.empty() || benchmark_name.find(filter) != std::string::npos;
+}
+
+int main(int argc, char* argv[]) {
+  std::string filter;
+
+  // Parse command-line arguments
+  for (int i = 1; i < argc; ++i) {
+      if (strcmp(argv[i], "-f") == 0 || strcmp(argv[i], "--filter") == 0) {
+          if (i + 1 < argc) {
+              filter = argv[++i];
+          } else {
+              std::cerr << "Error: -f/--filter requires an argument" << std::endl;
+              return EXIT_FAILURE;
+          }
+      }
+  }
+  // Testing correctness of round-trip (serialization + deserialization)
+  std::string json_str = read_file(JSON_FILE);
+
+  // Loading up the data into a structure.
+  simdjson::ondemand::parser parser;
+  simdjson::ondemand::document doc;
+  if(parser.iterate(simdjson::pad(json_str)).get(doc)) {
+    std::cerr << "Error loading the document!" << std::endl;
+    return EXIT_FAILURE;
+  }
+  TwitterData my_struct;
+  if(doc.get<TwitterData>().get(my_struct)) {
+    std::cerr << "Error loading TwitterData!" << std::endl;
+    return EXIT_FAILURE;
+  }
+
+  // Benchmarking the serialization
+  if (matches_filter("nlohmann", filter)) {
+    bench_nlohmann(my_struct);
+  }
+  if (matches_filter("simdjson_static_reflection", filter)) {
+    bench_simdjson_static_reflection(my_struct);
+  }
+#ifdef SIMDJSON_RUST_VERSION
+  if (matches_filter("rust", filter)) {
+    printf("# WARNING: The Rust benchmark may not be directly comparable since it does not use an equivalent data structure.\n");
+    serde_benchmark::TwitterData * td = serde_benchmark::twitter_from_str(json_str.c_str(), json_str.size());
+    bench_rust(td);
+    serde_benchmark::free_twitter(td);
+  }
+#endif
+#if SIMDJSON_BENCH_CPP_REFLECT
+  if (matches_filter("reflect_cpp", filter)) {
+    bench_reflect_cpp(my_struct);
+  }
+#endif
+  return EXIT_SUCCESS;
+}

benchmark/static_reflect/twitter_benchmark/nlohmann_twitter_data.h

@@ -0,0 +1,116 @@
+#ifndef NLOHMANN_TWITTER_DATA_H
+#define NLOHMANN_TWITTER_DATA_H
+
+#include "twitter_data.h"
+#include <nlohmann/json.hpp>
+
+void to_json(nlohmann::json &j, const User &u) {
+  j = nlohmann::json{{"id", u.id},
+                     {"name", u.name},
+                     {"screen_name", u.screen_name},
+                     {"location", u.location},
+                     {"description", u.description},
+                     {"verified", u.verified},
+                     {"followers_count", u.followers_count},
+                     {"friends_count", u.friends_count},
+                     {"statuses_count", u.statuses_count}};
+}
+
+void to_json(nlohmann::json &j, const Hashtag &h) {
+  j = nlohmann::json{{"text", h.text},
+                     {"indices_start", h.indices_start},
+                     {"indices_end", h.indices_end}};
+}
+
+void to_json(nlohmann::json &j, const Url &u) {
+  j = nlohmann::json{{"url", u.url},
+                     {"expanded_url", u.expanded_url},
+                     {"display_url", u.display_url},
+                     {"indices_start", u.indices_start},
+                     {"indices_end", u.indices_end}};
+}
+
+void to_json(nlohmann::json &j, const UserMention &um) {
+  j = nlohmann::json{{"id", um.id},
+                     {"name", um.name},
+                     {"screen_name", um.screen_name},
+                     {"indices_start", um.indices_start},
+                     {"indices_end", um.indices_end}};
+}
+
+void to_json(nlohmann::json &j, const Entities &e) {
+  j = nlohmann::json{{"hashtags", e.hashtags},
+                     {"urls", e.urls},
+                     {"user_mentions", e.user_mentions}};
+}
+
+void to_json(nlohmann::json &j, const Status &s) {
+  j = nlohmann::json{{"created_at", s.created_at},
+                     {"id", s.id},
+                     {"text", s.text},
+                     {"user", s.user},
+                     {"entities", s.entities},
+                     {"retweet_count", s.retweet_count},
+                     {"favorite_count", s.favorite_count},
+                     {"favorited", s.favorited},
+                     {"retweeted", s.retweeted}};
+}
+
+
+std::string nlohmann_serialize(const std::vector<Hashtag>& v) {
+  nlohmann::json a = nlohmann::json::array();
+  for(const Hashtag & h : v) {
+    a.push_back(nlohmann::json{{"text", h.text},
+                     {"indices_start", h.indices_start},
+                     {"indices_end", h.indices_end}});
+  }
+  return a.dump();
+}
+std::string nlohmann_serialize(const std::vector<Url>& v) {
+  nlohmann::json a = nlohmann::json::array();
+  for(const Url & u : v) {
+    a.push_back(nlohmann::json{{"url", u.url},
+                     {"expanded_url", u.expanded_url},
+                     {"display_url", u.display_url},
+                     {"indices_start", u.indices_start},
+                     {"indices_end", u.indices_end}});
+  }
+  return a.dump();
+}
+std::string nlohmann_serialize(const std::vector<UserMention>& v) {
+  nlohmann::json a = nlohmann::json::array();
+  for(const UserMention & um : v) {
+    a.push_back(nlohmann::json{{"id", um.id},
+                     {"name", um.name},
+                     {"screen_name", um.screen_name},
+                     {"indices_start", um.indices_start},
+                     {"indices_end", um.indices_end}});
+  }
+  return a.dump();
+}
+
+std::string nlohmann_serialize(const std::vector<Status>& v) {
+  nlohmann::json a = nlohmann::json::array();
+  for(const Status & s : v) {
+    a.push_back(nlohmann::json{{"created_at", s.created_at},
+                     {"id", s.id},
+                     {"text", s.text},
+                     {"user", s.user},
+                     {"entities", s.entities},
+                     {"retweet_count", s.retweet_count},
+                     {"favorite_count", s.favorite_count},
+                     {"favorited", s.favorited},
+                     {"retweeted", s.retweeted}});
+  }
+  return a.dump();
+}
+
+void to_json(nlohmann::json &j, const TwitterData &t) {
+  j = nlohmann::json{{"statuses", t.statuses}};
+}
+
+std::string nlohmann_serialize(const TwitterData &data) {
+  return nlohmann_serialize(data.statuses);
+}
+
+#endif // NLOHMANN_TWITTER_DATA_H

benchmark/static_reflect/twitter_benchmark/twitter_data.h

@@ -0,0 +1,71 @@
+#ifndef TWITTER_DATA_H
+#define TWITTER_DATA_H
+
+#include <string>
+#include <vector>
+
+struct User {
+  int64_t id;
+  std::string id_str;
+  std::string name;
+  std::string screen_name;
+  std::string location;
+  std::string description;
+  bool verified;
+  int64_t followers_count;
+  int64_t friends_count;
+  int64_t statuses_count;
+  bool operator<=>(const User &other) const = default;
+};
+
+struct Hashtag {
+  std::string text;
+  int64_t indices_start;
+  int64_t indices_end;
+  bool operator<=>(const Hashtag &other) const = default;
+};
+
+struct Url {
+  std::string url;
+  std::string expanded_url;
+  std::string display_url;
+  int64_t indices_start;
+  int64_t indices_end;
+  bool operator<=>(const Url &other) const = default;
+};
+
+struct UserMention {
+  int64_t id;
+  std::string name;
+  std::string screen_name;
+  int64_t indices_start;
+  int64_t indices_end;
+  bool operator<=>(const UserMention &other) const = default;
+};
+
+struct Entities {
+  std::vector<Hashtag> hashtags;
+  std::vector<Url> urls;
+  std::vector<UserMention> user_mentions;
+  bool operator==(const Entities &other) const = default;
+};
+
+struct Status {
+  std::string created_at;
+  int64_t id;
+  std::string text;
+  User user;
+  Entities entities;
+  int64_t retweet_count;
+  int64_t favorite_count;
+  bool favorited;
+  bool retweeted;
+  bool operator==(const Status &other) const = default;
+};
+
+struct TwitterData {
+  std::vector<Status> statuses;
+  bool operator==(const TwitterData &other) const = default;
+};
+
+#endif

benchmark/top_tweet/nlohmann_json.h

@@ -26,8 +26,8 @@ struct nlohmann_json {
       }
     }
 
-    result.text = top_tweet["text"];
-    result.screen_name = top_tweet["user"]["screen_name"];
+    result.text = to_string(top_tweet["text"]);
+    result.screen_name = to_string(top_tweet["user"]["screen_name"]);
     return result.retweet_count != -1;
   }
 };

benchmark/top_tweet/yyjson.h

@@ -51,18 +51,26 @@ struct yyjson_base {
 
 struct yyjson : yyjson_base {
   bool run(simdjson::padded_string &json, int64_t max_retweet_count, top_tweet_result<StringType> &result) {
-    return yyjson_base::run(yyjson_read(json.data(), json.size(), 0), max_retweet_count, result);
+    yyjson_doc *doc = yyjson_read(json.data(), json.size(), 0);
+    bool b = yyjson_base::run(doc, max_retweet_count, result);
+    yyjson_doc_free(doc);
+    return b;
   }
 };
 BENCHMARK_TEMPLATE(top_tweet, yyjson)->UseManualTime();
+
 #if SIMDJSON_COMPETITION_ONDEMAND_INSITU
 struct yyjson_insitu : yyjson_base {
   bool run(simdjson::padded_string &json, int64_t max_retweet_count, top_tweet_result<StringType> &result) {
-    return yyjson_base::run(yyjson_read_opts(json.data(), json.size(), YYJSON_READ_INSITU, 0, 0), max_retweet_count, result);
+    yyjson_doc *doc = yyjson_read_opts(json.data(), json.size(), YYJSON_READ_INSITU, 0, 0);
+    bool b = yyjson_base::run(doc, max_retweet_count, result);
+    yyjson_doc_free(doc);
+    return b;
   }
 };
 BENCHMARK_TEMPLATE(top_tweet, yyjson_insitu)->UseManualTime();
 #endif // SIMDJSON_COMPETITION_ONDEMAND_INSITU
+
 } // namespace top_tweet
 
 #endif // SIMDJSON_COMPETITION_YYJSON

cmake/CPM.cmake

@@ -0,0 +1,24 @@
+# SPDX-License-Identifier: MIT
+#
+# SPDX-FileCopyrightText: Copyright (c) 2019-2023 Lars Melchior and contributors
+
+set(CPM_DOWNLOAD_VERSION 0.40.2)
+set(CPM_HASH_SUM "c8cdc32c03816538ce22781ed72964dc864b2a34a310d3b7104812a5ca2d835d")
+
+if(CPM_SOURCE_CACHE)
+  set(CPM_DOWNLOAD_LOCATION "${CPM_SOURCE_CACHE}/cpm/CPM_${CPM_DOWNLOAD_VERSION}.cmake")
+elseif(DEFINED ENV{CPM_SOURCE_CACHE})
+  set(CPM_DOWNLOAD_LOCATION "$ENV{CPM_SOURCE_CACHE}/cpm/CPM_${CPM_DOWNLOAD_VERSION}.cmake")
+else()
+  set(CPM_DOWNLOAD_LOCATION "${CMAKE_BINARY_DIR}/cmake/CPM_${CPM_DOWNLOAD_VERSION}.cmake")
+endif()
+
+# Expand relative path. This is important if the provided path contains a tilde (~)
+get_filename_component(CPM_DOWNLOAD_LOCATION ${CPM_DOWNLOAD_LOCATION} ABSOLUTE)
+
+file(DOWNLOAD
+     https://github.com/cpm-cmake/CPM.cmake/releases/download/v${CPM_DOWNLOAD_VERSION}/CPM.cmake
+     ${CPM_DOWNLOAD_LOCATION} EXPECTED_HASH SHA256=${CPM_HASH_SUM}
+)
+
+include(${CPM_DOWNLOAD_LOCATION})

cmake/developer-options.cmake

@@ -2,7 +2,10 @@
 # Flags used by exes and by the simdjson library (project-wide flags)
 #
 add_library(simdjson-internal-flags INTERFACE)
-
+if(NOT DEFINED CMAKE_POSITION_INDEPENDENT_CODE)
+  # We default to ON for all targets, so that we can use the library in shared libraries.
+  set_target_properties(simdjson-internal-flags PROPERTIES INTERFACE_POSITION_INDEPENDENT_CODE ON)
+endif(NOT DEFINED CMAKE_POSITION_INDEPENDENT_CODE)
 
 option(SIMDJSON_CHECK_EOF "Check for the end of the input buffer. The setting is unnecessary since we require padding of the inputs. You should expect tests to fail with this option turned on." OFF)
 if(SIMDJSON_CHECK_EOF)
@@ -29,6 +32,9 @@ undefined behavior.")
     link_libraries(
         -fsanitize=address -fno-omit-frame-pointer -fno-sanitize-recover=all
     )
+  elseif (CMAKE_CXX_COMPILER_ID STREQUAL "MSVC")
+    add_compile_options(-fsanitize=address)
+    link_libraries(-fsanitize=address)
   else()
     message(
         STATUS
@@ -52,7 +58,6 @@ endif()
 
 option(SIMDJSON_SANITIZE_MEMORY "Sanitize memory" OFF)
 
-
 if(SIMDJSON_SANITIZE_MEMORY)
   message(STATUS "Setting the memory sanitizer.")
   add_compile_options(
@@ -110,8 +115,14 @@ endif()
 
 # We compile tools, tests, etc. with C++ 17. Override yourself if you need on a
 # target.
-set(SIMDJSON_CXX_STANDARD 17 CACHE STRING "the C++ standard to use for simdjson")
-set(CMAKE_CXX_STANDARD ${SIMDJSON_CXX_STANDARD})
+if(SIMDJSON_STATIC_REFLECTION)
+  # This is temporary.
+  set(SIMDJSON_CXX_STANDARD 26 CACHE STRING "the C++ standard to use for simdjson")
+  #set(CMAKE_CXX_STANDARD ${SIMDJSON_CXX_STANDARD})
+else()
+  set(SIMDJSON_CXX_STANDARD 17 CACHE STRING "the C++ standard to use for simdjson")
+  set(CMAKE_CXX_STANDARD ${SIMDJSON_CXX_STANDARD})
+endif()
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
 set(CMAKE_CXX_EXTENSIONS OFF)
 set(CMAKE_THREAD_PREFER_PTHREAD ON)
@@ -158,14 +169,15 @@ We recommend Visual Studio 2019 or better on a 64-bit system.")
     add_compile_options(/Zi)
   endif()
 else()
-  if(NOT WIN32)
-    target_compile_options(simdjson-internal-flags INTERFACE -fPIC)
-  endif()
   target_compile_options(
       simdjson-internal-flags INTERFACE
       -Werror -Wall -Wextra -Weffc++ -Wsign-compare -Wshadow -Wwrite-strings
       -Wpointer-arith -Winit-self -Wconversion -Wno-sign-conversion
   )
+  if(CMAKE_CXX_STANDARD VERSION_GREATER_EQUAL 20)
+    target_compile_options(simdjson-internal-flags INTERFACE -Wctad-maybe-unsupported)
+  endif()
+
 endif()
 
 option(SIMDJSON_GLIBCXX_ASSERTIONS "Set _GLIBCXX_ASSERTIONS" OFF)

cmake/exception-flags.cmake

@@ -17,8 +17,9 @@ editing CMAKE_CXX_FLAGS")
     # /EHc used in conjection with /EHs indicates that extern "C" functions
     # never throw (terminate-on-throw)
     # Here, we disable both with the - argument negation operator
-    string(REPLACE "/EHsc" "/EHs-c-" CMAKE_CXX_FLAGS ${CMAKE_CXX_FLAGS})
-
+    if(CMAKE_CXX_FLAGS)
+        string(REPLACE "/EHsc" "/EHs-c-" CMAKE_CXX_FLAGS ${CMAKE_CXX_FLAGS})
+    endif()
     # Because we cannot change the flag above on an individual target (yet), the
     # definition below must similarly be added globally
     add_definitions(-D_HAS_EXCEPTIONS=0)

cmake/toolchains-ci/riscv64-linux-gnu.cmake

@@ -0,0 +1,4 @@
+set(CMAKE_SYSTEM_NAME Linux)
+set(CMAKE_SYSTEM_PROCESSOR riscv64)
+
+set(CMAKE_CROSSCOMPILING_EMULATOR "qemu-riscv64-static")

dependencies/CMakeLists.txt

@@ -1,5 +1,4 @@
 include(CMakeDependentOption)
-include(import.cmake)
 
 option(SIMDJSON_ALLOW_DOWNLOADS
         "Allow dependencies to be downloaded during configure time"
@@ -8,20 +7,24 @@ option(SIMDJSON_ALLOW_DOWNLOADS
 cmake_dependent_option(SIMDJSON_COMPETITION "Compile competitive benchmarks" ON
         SIMDJSON_ALLOW_DOWNLOADS OFF)
 cmake_dependent_option(SIMDJSON_GOOGLE_BENCHMARKS "compile the Google Benchmark benchmarks" ON
-        SIMDJSON_ALLOW_DOWNLOADS OFF)
+        "SIMDJSON_ALLOW_DOWNLOADS OR MINGW" OFF)
 
 if(SIMDJSON_GOOGLE_BENCHMARKS)
-  set_off(BENCHMARK_ENABLE_TESTING)
-  set_off(BENCHMARK_ENABLE_INSTALL)
-  set_off(BENCHMARK_ENABLE_WERROR)
-
-  import_dependency(google_benchmarks google/benchmark v1.7.1)
-  add_dependency(google_benchmarks)
+  CPMAddPackage(
+        NAME google_benchmarks
+        URL https://github.com/google/benchmark/archive/refs/tags/v1.9.4.zip
+        OPTIONS
+        "BENCHMARK_ENABLE_TESTING OFF"
+        "BENCHMARK_ENABLE_INSTALL OFF"
+        "BENCHMARK_ENABLE_WERROR OFF"
+  )
 endif()
 
-# The bulk of our benchmarking and testing data has been moved simdjson/simdjson-data
-import_dependency(simdjson-data simdjson/simdjson-data a5b13babe65c1bba7186b41b43d4cbdc20a5c470)
-add_dependency(simdjson-data)
+CPMAddPackage(
+        NAME simdjson-data
+        URL https://github.com/simdjson/simdjson-data/archive/351949906abde446f0314bf79606fb5d884f5be7.zip
+)
+
 option(SIMDJSON_USE_BOOST_JSON "Try to include BOOST_JSON, this may break your binaries under some systems." OFF)
 # This prevents variables declared with set() from unnecessarily escaping and
 # should not be called more than once
@@ -38,20 +41,30 @@ function(competition_scope_)
 int main() {}
 ]] SIMDJSON_FOUND_STRING_VIEW)
   if(SIMDJSON_FOUND_STRING_VIEW AND SIMDJSON_USE_BOOST_JSON)
-    import_dependency(boostjson boostorg/json ee8d72d)
+    CPMAddPackage(
+        NAME boostjson
+        URL https://github.com/boostorg/json/archive/ee8d72d8502b409b5561200299cad30ccdb91415.zip
+    )
     add_library(boostjson STATIC "${boostjson_SOURCE_DIR}/src/src.cpp")
     target_compile_definitions(boostjson PUBLIC BOOST_JSON_STANDALONE)
     target_include_directories(boostjson SYSTEM PUBLIC
             "${boostjson_SOURCE_DIR}/include")
     target_compile_definitions(boostjson INTERFACE SIMDJSON_COMPETITION_BOOSTJSON)
   endif()
-
-  import_dependency(cjson DaveGamble/cJSON c69134d)
+  CPMAddPackage(
+      NAME cjson
+      URL https://github.com/DaveGamble/cJSON/archive/c69134d01746dcf551dd7724b4edb12f922eb0d1.zip
+      DOWNLOAD_ONLY YES
+  )
   add_library(cjson STATIC "${cjson_SOURCE_DIR}/cJSON.c")
   target_include_directories(cjson SYSTEM PUBLIC "${cjson_SOURCE_DIR}")
   target_compile_definitions(cjson INTERFACE SIMDJSON_COMPETITION_CJSON)
 
-  import_dependency(fastjson mikeando/fastjson 485f994)
+  CPMAddPackage(
+      NAME fastjson
+      URL https://github.com/mikeando/fastjson/archive/485f994a61a64ac73fa6a40d4d639b99b463563b.zip
+      DOWNLOAD_ONLY YES
+  )
   add_library(fastjson STATIC
           "${fastjson_SOURCE_DIR}/src/fastjson.cpp"
           "${fastjson_SOURCE_DIR}/src/fastjson2.cpp"
@@ -60,38 +73,42 @@ int main() {}
           "${fastjson_SOURCE_DIR}/include")
   target_compile_definitions(fastjson INTERFACE SIMDJSON_COMPETITION_FASTJSON)
 
-  import_dependency(gason vivkin/gason 7aee524)
+  CPMAddPackage(
+      NAME gason
+      URL https://github.com/vivkin/gason/archive/7aee524189da1c1ecd19f67981e3d903dae25470.zip
+      DOWNLOAD_ONLY YES
+  )
   add_library(gason STATIC "${gason_SOURCE_DIR}/src/gason.cpp")
   target_include_directories(gason SYSTEM PUBLIC "${gason_SOURCE_DIR}/src")
   target_compile_definitions(gason INTERFACE SIMDJSON_COMPETITION_GASON)
 
-  import_dependency(jsmn zserge/jsmn 18e9fe4)
+  CPMAddPackage(
+      NAME jsmn
+      URL https://github.com/zserge/jsmn/archive/18e9fe42cbfe21d65076f5c77ae2be379ad1270f.zip
+      DOWNLOAD_ONLY YES
+  )
   add_library(jsmn STATIC "${jsmn_SOURCE_DIR}/jsmn.c")
   target_include_directories(jsmn SYSTEM PUBLIC "${jsmn_SOURCE_DIR}")
   target_compile_definitions(jsmn INTERFACE SIMDJSON_COMPETITION_JSMN)
 
-  message(STATUS "Importing json (nlohmann/json@v3.10.5)")
-  set(nlohmann_json_SOURCE_DIR "${dep_root}/json")
-  if(NOT EXISTS "${nlohmann_json_SOURCE_DIR}")
-    file(DOWNLOAD
-            "https://github.com/nlohmann/json/releases/download/v3.10.5/json.hpp"
-            "${nlohmann_json_SOURCE_DIR}/nlohmann/json.hpp")
-  endif()
-  add_library(nlohmann_json INTERFACE)
-  target_include_directories(nlohmann_json SYSTEM INTERFACE "${nlohmann_json_SOURCE_DIR}")
-  target_compile_definitions(nlohmann_json INTERFACE SIMDJSON_COMPETITION_NLOHMANN_JSON)
+  CPMAddPackage(
+      NAME nlohmann_json
+      URL https://github.com/nlohmann/json/archive/refs/tags/v3.12.0.zip
+  )
+
+  set_property(TARGET nlohmann_json APPEND PROPERTY INTERFACE_COMPILE_DEFINITIONS SIMDJSON_COMPETITION_NLOHMANN_JSON)
 
-  import_dependency(json11 dropbox/json11 ec4e452)
-  add_library(json11 STATIC "${json11_SOURCE_DIR}/json11.cpp")
-  target_include_directories(json11 SYSTEM PUBLIC "${json11_SOURCE_DIR}")
-  target_compile_definitions(json11 INTERFACE SIMDJSON_COMPETITION_JSON11)
 
   set(jsoncpp_SOURCE_DIR "${simdjson_SOURCE_DIR}/dependencies/jsoncppdist")
   add_library(jsoncpp STATIC "${jsoncpp_SOURCE_DIR}/jsoncpp.cpp")
   target_include_directories(jsoncpp SYSTEM PUBLIC "${jsoncpp_SOURCE_DIR}")
   target_compile_definitions(jsoncpp INTERFACE SIMDJSON_COMPETITION_JSONCPP)
 
-  import_dependency(rapidjson Tencent/rapidjson f54b0e4)
+  CPMAddPackage(
+      NAME rapidjson
+      URL https://github.com/Tencent/rapidjson/archive/805d7ed5dfe97a39b8b0816fd5eeed8731dc4936.zip
+      DOWNLOAD_ONLY YES
+  )
   add_library(rapidjson INTERFACE)
   target_compile_definitions(rapidjson INTERFACE RAPIDJSON_HAS_STDSTRING)
   include (TestBigEndian)
@@ -110,14 +127,22 @@ int main() {}
     target_compile_definitions(rapidjson INTERFACE SIMDJSON_COMPETITION_RAPIDJSON)
   endif()
 
-  import_dependency(sajson chadaustin/sajson 2dcfd35)
+  CPMAddPackage(
+      NAME sajson
+      URL https://github.com/chadaustin/sajson/archive/2dcfd350586375f9910f74821d4f07d67ae455ba.zip
+      DOWNLOAD_ONLY YES
+  )
   add_library(sajson INTERFACE)
   target_compile_definitions(sajson INTERFACE SAJSON_UNSORTED_OBJECT_KEYS)
   target_include_directories(sajson SYSTEM INTERFACE
           "${sajson_SOURCE_DIR}/include")
   target_compile_definitions(sajson INTERFACE SIMDJSON_COMPETITION_SAJSON)
 
-  import_dependency(ujson4c esnme/ujson4c e14f3fd)
+  CPMAddPackage(
+      NAME ujson4c
+      URL https://github.com/esnme/ujson4c/archive/e14f3fd5207fe30d1bdea723f260609e69d1abfa.zip
+      DOWNLOAD_ONLY YES
+  )
   add_library(ujson4c STATIC
           "${ujson4c_SOURCE_DIR}/src/ujdecode.c"
           "${ujson4c_SOURCE_DIR}/3rdparty/ultrajsondec.c")
@@ -126,7 +151,11 @@ int main() {}
           "${ujson4c_SOURCE_DIR}/3rdparty")
   target_compile_definitions(ujson4c INTERFACE SIMDJSON_COMPETITION_UJSON4C)
 
-  import_dependency(yyjson ibireme/yyjson c385651)
+  CPMAddPackage(
+      NAME yyjson
+      URL https://github.com/ibireme/yyjson/archive/c3856514de0a67d7b66939bf3ed491a2d6e61277.zip
+      DOWNLOAD_ONLY YES
+  )
   add_library(yyjson STATIC "${yyjson_SOURCE_DIR}/src/yyjson.c")
   target_include_directories(yyjson SYSTEM PUBLIC "${yyjson_SOURCE_DIR}/src")
   target_compile_definitions(yyjson INTERFACE SIMDJSON_COMPETITION_YYJSON)
@@ -140,7 +169,7 @@ int main() {}
   endif()
 
   add_library(competition-all INTERFACE)
-  target_link_libraries(competition-all INTERFACE competition-core jsoncpp json11 fastjson gason ujson4c)
+  target_link_libraries(competition-all INTERFACE competition-core jsoncpp fastjson gason ujson4c)
 endfunction()
 
 if(SIMDJSON_COMPETITION)
@@ -151,10 +180,12 @@ cmake_dependent_option(SIMDJSON_CXXOPTS "Download cxxopts (necessary for tools)"
         SIMDJSON_ALLOW_DOWNLOADS OFF)
 
 if(SIMDJSON_CXXOPTS)
-  set_off(CXXOPTS_BUILD_EXAMPLES)
-  set_off(CXXOPTS_BUILD_TESTS)
-  set_off(CXXOPTS_ENABLE_INSTALL)
-
-  import_dependency(cxxopts jarro2783/cxxopts 794c975)
-  add_dependency(cxxopts)
+  CPMAddPackage(
+        NAME cxxopts
+        URL https://github.com/jarro2783/cxxopts/archive/59656709c0c58fcd0ed18b38e02938dbe05284c5.zip
+        OPTIONS
+        "CXXOPTS_BUILD_EXAMPLES OFF"
+        "CXXOPTS_BUILD_TESTS OFF"
+        "CXXOPTS_ENABLE_INSTALL OFF"
+  )
 endif()

dependencies/import.cmake

@@ -1,48 +0,0 @@
-set(dep_root "${simdjson_SOURCE_DIR}/dependencies/.cache")
-if(DEFINED ENV{simdjson_DEPENDENCY_CACHE_DIR})
-  set(dep_root "$ENV{simdjson_DEPENDENCY_CACHE_DIR}")
-endif()
-
-function(import_dependency NAME GITHUB_REPO COMMIT)
-  message(STATUS "Importing ${NAME} (${GITHUB_REPO}@${COMMIT})")
-  set(target "${dep_root}/${NAME}")
-
-  # If the folder exists in the cache, then we assume that everything is as
-  # should be and do nothing
-  if(EXISTS "${target}")
-    set("${NAME}_SOURCE_DIR" "${target}" PARENT_SCOPE)
-    return()
-  endif()
-
-  set(zip_url "https://github.com/${GITHUB_REPO}/archive/${COMMIT}.zip")
-  set(archive "${dep_root}/archive.zip")
-  set(dest "${dep_root}/_extract")
-
-  file(DOWNLOAD "${zip_url}" "${archive}")
-  file(MAKE_DIRECTORY "${dest}")
-  execute_process(
-          WORKING_DIRECTORY "${dest}"
-          COMMAND "${CMAKE_COMMAND}" -E tar xf "${archive}")
-  file(REMOVE "${archive}")
-
-  # GitHub archives only ever have one folder component at the root, so this
-  # will always match that single folder
-  file(GLOB dir LIST_DIRECTORIES YES "${dest}/*")
-
-  file(RENAME "${dir}" "${target}")
-
-  set("${NAME}_SOURCE_DIR" "${target}" PARENT_SCOPE)
-endfunction()
-
-# Delegates to the dependency
-macro(add_dependency NAME)
-  if(NOT DEFINED "${NAME}_SOURCE_DIR")
-    message(FATAL_ERROR "Missing ${NAME}_SOURCE_DIR variable")
-  endif()
-
-  add_subdirectory("${${NAME}_SOURCE_DIR}" "${PROJECT_BINARY_DIR}/_deps/${NAME}" EXCLUDE_FROM_ALL)
-endmacro()
-
-function(set_off NAME)
-  set("${NAME}" OFF CACHE INTERNAL "")
-endfunction()

doc/basics_doxygen.md

@@ -1,5 +1,8 @@
 We take our documentation seriously. Please start reading the documentation before you attempt to use simdjson. We hope you will enjoy reading us.
 
-* Basics: https://github.com/simdjson/simdjson/blob/master/doc/basics.md is an overview of how to use simdjson and its APIs.
-* iterate_many: https://github.com/simdjson/simdjson/blob/master/doc/iterate_many.md describes an interface providing features to work with files or streams containing multiple small JSON documents. As fast and convenient as possible.
-* Performance: https://github.com/simdjson/simdjson/blob/master/doc/performance.md shows some more advanced scenarios and how to tune for them.
+* [Basics](doc/basics.md) is an overview of how to use simdjson and its APIs.
+* [Builder](doc/builder.md) is an overview of how to efficiently write JSON strings using simdjson.
+* [Performance](doc/performance.md) shows some more advanced scenarios and how to tune for them.
+* [Implementation Selection](doc/implementation-selection.md) describes runtime CPU detection and
+  how you can work with it.
+* [API](https://simdjson.github.io/simdjson/) contains the automatically generated API documentation.

doc/builder.md

@@ -0,0 +1,366 @@
+Builder
+==========
+
+Sometimes you want to generate JSON string outputs efficiently.
+The simdjson library provides high-performance low-level facilities.
+When using these low-level functionalities, you are responsible to
+define the structure of your JSON document. Our more advanced interface
+automates the process using C++26 static reflection: you get both high
+speed and high convenience.
+
+- [Builder](#builder)
+  * [Overview: string_builder](#overview--string-builder)
+  * [Example: string_builder](#example--string-builder)
+  * [C++26 static reflection](#c--26-static-reflection)
+    + [Without `string_buffer` instance](#without--string-buffer--instance)
+    + [Without `string_buffer` instance but with explicit error handling](#without--string-buffer--instance-but-with-explicit-error-handling)
+
+Overview: string_builder
+---------------------------
+
+The string_builder class is a low-level utility for constructing JSON strings representing documents. It is optimized for performance, potentially leveraging kernel-specific features like SIMD instructions for tasks such as string escaping. This class supports atomic types (e.g., booleans, numbers, strings) but does not handle composed types directly (like arrays or objects).
+Note that JSON strings are always encoded as UTF-8.
+
+An `string_builder` is created with an initial buffer capacity (e.g., 1kB). The memory
+is reallocated when needed.
+The efficiency of `string_builder` stems from its internal use of a resizable array or buffer. When you append data, it adds the characters to this buffer, resizing it only when necessary, typically in a way that minimizes reallocations. This approach contrasts with regular string concatenation, where each operation creates a new string, copying all previous content, leading to quadratic time complexity for repeated concatenations.
+
+
+It has the following methods to add content to the string:
+
+
+- `append(number_type v)`: Appends a number (including booleans) to the JSON buffer. Booleans are converted to the strings "false" or "true". Numbers are formatted according to the JSON standard, with floating-point numbers using the shortest representation that accurately reflects the value.
+- `append(char c)`: Appends a single character to the JSON buffer.
+- `append_null()`: Appends the string "null" to the JSON buffer.
+- `clear()`: Clears the contents of the JSON buffer, resetting the position to 0 while retaining the allocated capacity.
+- `escape_and_append(std::string_view input)`: Appends a string view to the JSON buffer after escaping special characters (e.g., quotes, backslashes) as required by JSON.
+- `escape_and_append_with_quotes(std::string_view input)` Appends a string view surrounded by double quotes (e.g., "input") to the JSON buffer after escaping special characters. For constant strings, you may also do `escape_and_append_with_quotes<"mystring">()`.
+- `escape_and_append_with_quotes(char input)`: Appends a single character surrounded by double quotes (e.g., "c") to the JSON buffer after escaping it if necessary.
+- `append_raw(const char *c)`: Appends a null-terminated C string directly to the JSON buffer without escaping.
+- `append_raw(std::string_view input)`: Appends a string view directly to the JSON buffer without escaping.
+- `append_raw(const char *str, size_t len)`: Appends a specified number of characters from a C string directly to the JSON
+- `append_key_value(key,value)`: Appends a key and a value (`"json":somevalue`)
+- `append_key_value<"mykey">(value)`: Appends a key and a value (`"json":somevalue`), useful when the key is a compile-time constant (C++20).
+
+After writing the content, if you have reasons to believe that the content might violate UTF-8 conventions, you can check it as follows:
+
+- `validate_unicode()`: Checks if the content in the JSON buffer is valid UTF-8. Returns: true if the content is valid UTF-8, false otherwise.
+
+You might need to do unicode validation if you have strings in your data structures containing
+malformed UTF-8. Note that we do not automatically call `validate_unicode()`.
+
+Once you are satisfied, you can recover the string as follows:
+
+- `operator std::string()`: Converts the JSON buffer to an std::string. (Might throw if an error occurred.)
+- `operator std::string_view()`: Converts the JSON buffer to an std::string_view.  (Might throw if an error occurred.)
+- `view()`: Returns a view of the written JSON buffer as a `simdjson_result<std::string_view>` (C++20).
+
+The later method (`view()`) is recommended.  For performance reasons, we expect you to explicitly call `validate_unicode()` as needed (e.g., prior to calling `view()`).
+
+Example: string_builder
+---------------------------
+
+```cpp
+struct Car {
+    std::string make;
+    std::string model;
+    int64_t year;
+    std::vector<double> tire_pressure;
+};
+
+void serialize_car(const Car& car, simdjson::builder::string_builder& builder) {
+    // start of JSON
+    builder.start_object();
+
+    // "make"
+    builder.append_key_value("make", car.make);
+    builder.append_comma();
+
+    // "model"
+    builder.append_key_value("model", car.model);
+    builder.append_comma();
+
+    // "year"
+    builder.append_key_value("year", car.year);
+    builder.append_comma();
+
+    // "tire_pressure"
+    builder.escape_and_append_with_quotes("tire_pressure");
+    builder.append_colon();
+    builder.start_array();
+    // vector tire_pressure
+    for (size_t i = 0; i < car.tire_pressure.size(); ++i) {
+        builder.append(car.tire_pressure[i]);
+        if (i < car.tire_pressure.size() - 1) {
+            builder.append_comma();
+        }
+    }
+    builder.end_array();
+    builder.end_object();
+}
+
+bool car_test() {
+    simdjson::builder::string_builder sb;
+    Car c = {"Toyota", "Corolla", 2017, {30.0,30.2,30.513,30.79}};
+    serialize_car(c, sb);
+    std::string_view p{sb};
+    // p holds the JSON:
+    // "{\"make\":\"Toyota\",\"model\":\"Corolla\",\"year\":2017,\"tire_pressure\":[30.0,30.2,30.513,30.79]}"
+    return true;
+}
+```
+
+
+
+
+The `string_builder` constructor takes an optional parameter which specifies the initial
+memory allocation in byte. If you know approximately the size of your JSON output, you can
+pass this value as a parameter (e.g., `simdjson::builder::string_builder sb{1233213}`).
+
+The `string_builder` might throw an exception in case of error when you cast it result to `std::string_view`. If you wish to avoid exceptions, you can use the following programming pattern:
+
+```cpp
+    std::string_view p;
+    if(sb.view().get(p)) {
+        return false; // there was an error
+    }
+```
+
+In all cases, the `std::string_view` instance depends the corresponding `string_builder` instance.
+
+### C++20
+
+
+
+If you have C++20, you can simplify the code, as the `std::vector<double>` is automatically supported. Further, we can pass the keys (which are compile-time
+constant) as template parameter (for improved performance).
+
+```cpp
+    Car c = {"Toyota", "Corolla", 2017, {30.0,30.2,30.513,30.79}};
+    simdjson::builder::string_builder sb;
+    sb.start_object();
+    sb.append_key_value<"make">(c.make);
+    sb.append_comma();
+    sb.append_key_value<"model">(c.model);
+    sb.append_comma();
+    sb.append_key_value<"year">(c.year);
+    sb.append_comma();
+    sb.append_key_value<"tire_pressure">(c.tire_pressure);
+    sb.end_object();
+    std::string_view p = sb.view();
+```
+
+With C++20, you can similarly handle standard containers transparently.
+For example, you can serialize `std::map<std::string,T>` types.
+
+```cpp
+    std::map<std::string,double> c = {{"key1", 1}, {"key2", 1}};
+    simdjson::builder::string_builder sb;
+    sb.append(c);
+    std::string_view p = sb.view();
+```
+
+You can also serialize `std::vector<T>` types.
+
+```cpp
+    std::vector<std::vector<double>> c = {{1.0, 2.0}, {3.0, 4.0}};
+    simdjson::builder::string_builder sb;
+    sb.append(c);
+    std::string_view p = sb.view();
+```
+
+You can also skip the creation for the `string_builder` instance in such simple cases.
+
+```cpp
+std::vector<std::vector<double>> c = {{1.0, 2.0}, {3.0, 4.0}};
+std::string json = simdjson::to_json(c);
+```
+
+We also have an overload for when you want to reuse the same `std::string` instance:
+
+
+```cpp
+std::vector<std::vector<double>> c = {{1.0, 2.0}, {3.0, 4.0}};
+std::string json;
+auto error = simdjson::to_json(c, json);
+if(error) { /* there was an error */ }
+```
+
+
+We do recommend that you create and reuse the `string_builder` instance for performance
+reasons.
+
+You can also add custom serialization functions using a `tag_invoke` function.
+For example, the following
+function will allow you to serialize instances of the type `Car`.
+
+```cpp
+#include <simdjson>
+
+struct Car {
+  std::string make;
+  std::string model;
+  int64_t year;
+  std::vector<float> tire_pressure;
+};
+
+namespace simdjson {
+
+template <typename builder_type>
+void tag_invoke(serialize_tag, builder_type &builder, const Car& car) {
+  builder.start_object();
+  builder.append_key_value("make", car.make);
+  builder.append_comma();
+  builder.append_key_value("model", car.model);
+  builder.append_comma();
+  builder.append_key_value("year", car.year);
+  builder.append_comma();
+  builder.append_key_value("tire_pressure", car.tire_pressure);
+  builder.end_object();
+}
+
+} // namespace simdjson
+```
+
+C++26 static reflection
+------------------------
+
+Static reflection (or compile-time reflection) in C++26 introduces a powerful compile-time mechanism that allows a program to inspect and manipulate its own structure, such as types, variables, functions, and other program elements, during compilation. Unlike runtime reflection in languages like Java or Python, C++26’s static reflection operates entirely at compile time, aligning with C++’s emphasis on zero-overhead abstractions and high performance. It means
+that you can delegate much of the work to the library.
+If you have a compiler with support C++26 static reflection, you can compile
+your code with the `SIMDJSON_STATIC_REFLECTION` macro set:
+
+```cpp
+#define SIMDJSON_STATIC_REFLECTION 1
+//...
+#include "simdjson.h"
+```
+
+And then you can append your data structures to a `string_builder` instance
+automatically. In most cases, it should work automatically:
+
+```cpp
+    struct Car {
+        std::string make;
+        std::string model;
+        int64_t year;
+        std::vector<double> tire_pressure;
+    };
+
+    bool car_test() {
+        simdjson::builder::string_builder sb;
+        Car c = {"Toyota", "Corolla", 2017, {30.0,30.2,30.513,30.79}};
+        sb << c;
+        std::string_view p{sb};
+        // p holds the JSON:
+        // "{\"make\":\"Toyota\",\"model\":\"Corolla\",\"year\":2017,\"tire_pressure\":[30.0,30.2,30.513,30.79]}"
+        return true;
+    }
+```
+
+
+### Without `string_buffer` instance
+
+In some instances, you might want to create a string directly from your own data type.
+You can create a string directly, without an explicit `string_builder` instance
+with the `simdjson::to_json` template function.
+(Under the hood a `string_builder` instance may still be created.)
+
+```cpp
+    struct Car {
+        std::string make;
+        std::string model;
+        int64_t year;
+        std::vector<double> tire_pressure;
+    };
+
+    void f() {
+        Car c = {"Toyota", "Corolla", 2017, {30.0,30.2,30.513,30.79}};
+        std::string json = simdjson::to_json(c);
+    }
+```
+
+If you know the output size, in bytes, of your JSON string, you may
+pass it as a second parameter (e.g., `simdjson::to_json(c, 31123)`).
+
+Sometimes you may want to reuse the same `std::string` instance. We
+have an overload for this purpose:
+
+```cpp
+Car c = {"Toyota", "Corolla", 2017, {30.0,30.2,30.513,30.79}};
+std::string s;
+auto error = simdjson::to_json(c, s);
+if(error) { /* there was an error */ }
+```
+
+You can then also add a third parameter for the expected output size in bytes.
+
+### Extracting just some fields
+In some instances, your class might have many fields that you do not want to serialize.
+You can achieve this result with the `simdjson::extract_from` template. In the following
+example, we serialize only the `year` and `price` fields on the `Car` instance.
+```cpp
+struct Car {
+    std::string make;
+    std::string model;
+    int year;
+    double price;
+    bool electric;
+};
+Car car{"Ford", "F-150", 2024, 55000.0, false};
+// Extract year and price
+std::string json_result = simdjson::extract_from<"year", "price">(car);
+// Alternatively:
+// std::string json_result;
+// auto error =  extract_from<"year", "price">(car).get(json_result);
+// if(error) { /* error handling */ }
+```
+
+### Without `string_buffer` instance but with explicit error handling
+
+If prefer a version without exceptions and explicit error handling, you can use the following
+pattern:
+
+```cpp
+  std::string json;
+  if(simdjson::to_json(c).get(json)) {
+    // there was an error
+  } else {
+    // json contain the serialized JSON
+  }
+```
+
+### Customization
+
+If you want to serialize a value in a custome way, you can do it with a
+`tag_invoke` specialization like the following example which will map
+the year attribute to a string.
+
+
+```cpp
+#include <simdjson>
+
+struct Car {
+  std::string make;
+  std::string model;
+  int64_t year;
+  std::vector<float> tire_pressure;
+};
+
+namespace simdjson {
+
+template <typename builder_type>
+void tag_invoke(serialize_tag, builder_type &builder, const Car& car) {
+  builder.start_object();
+  builder.append_key_value("make", car.make);
+  builder.append_comma();
+  builder.append_key_value("model", car.model);
+  builder.append_comma();
+  builder.append_key_value("year", std::to_string(car.year));
+  builder.append_comma();
+  builder.append_key_value("tire_pressure", car.tire_pressure);
+  builder.end_object();
+}
+
+} // namespace simdjson
+```

doc/compile_time.md

@@ -0,0 +1,227 @@
+# Parse json at compile time
+   * [Introduction](#introduction)
+   * [Example](#example)
+   * [Concepts](#concepts)
+   * [Loading from disk](#loading-from-disk)
+   * [Limitations (compile-time errors)](#limitations-compile-time-errors)
+
+
+## Introduction
+In some instances, you may want to configure your software at compile-time with a JSON document.
+Maybe you have a single code base but many different possible configurations, all resulting in
+different software. For example, you might be programming robots, using the same software, but
+different robot configurations.
+
+To achieve the desired result, you have a few options. You may start the software and parser a
+JSON file at runtime. Or you might convert your JSON data into C++ code that you can compile with
+your software.
+
+With C++26, there is another way: parse the JSON file along with your C++ code. In this manner,
+the JSON data becomes native C++ data.
+
+The simdjson library supports parsing JSON documents at compile time if you have C++26 support. To
+activate C++26 reflection support, you can compile
+your code with the `SIMDJSON_STATIC_REFLECTION` macro set:
+
+```cpp
+#define SIMDJSON_STATIC_REFLECTION 1
+//...
+#include "simdjson.h"
+```
+
+The `simdjson::compile_time::parse_json` function parses a JSON document at **compile time** and returns a `constexpr` structure reflecting its content. We support the full range of JSON values, which are mapped to C++ types as in
+the following table.
+
+
+| JSON type      | C++ type                         |
+|----------------|----------------------------------|
+| object         | anonymous struct                 |
+| array          | `std::array<T, N>` (homogeneous) |
+| string         | `const char*` (UTF-8)            |
+| number         | `int64_t`, `uint64_t`, `double`  |
+| `true`/`false` | `bool`                           |
+| `null`         | `std::nullptr_t`                 |
+
+## Example
+
+Suppose you want to parse the following JSON document:
+
+```cpp
+{
+    "port": 8080,
+    "host": "localhost",
+    "debug": true
+}
+```
+
+**Reminder**: In C++, `R"( )"` allows us to write multi-line strings with unescaped quotes.
+
+
+You can do so, at compile-time, as follows:
+
+
+```cpp
+constexpr auto cfg = R"(
+
+{
+    "port": 8080,
+    "host": "localhost",
+    "debug": true
+}
+
+)"_json;
+
+// cfg.port == 8080
+// std::string_view(cfg.host) == "localhost"
+// cfg.debug == true
+```
+
+You can nest objects and arrays:
+
+```cpp
+constexpr auto data = R"(
+
+{
+    "servers": [
+        {"host": "s1", "port": 3000},
+        {"host": "s2", "port": 3001}
+    ]
+}
+
+)"_json;
+
+
+// data.servers.size() == 2
+// std::string_view(data.servers[0].host) == "s1"
+```
+
+Top-level arrays are allowed:
+
+```cpp
+constexpr auto arr = R"(
+
+[1, 2, 3]
+
+)"_json;
+static_assert(arr.size() == 3);
+static_assert(arr[1] == 2);
+```
+
+
+## Concepts
+
+Given that the parsed data is made of structures that depend on the JSON input, you might
+want to check that it conforms to your expectation. You can do so with concepts.
+
+Let us consider this example:
+
+```cpp
+    constexpr auto config = R"(
+
+    [
+      { "name": "Alice", "age": 30 },
+      { "name": "Bob", "age": 25 },
+      { "name": "Charlie", "age": 35 }
+    ]
+
+    )"_json;
+```
+
+You might want to ensure that the result is an array of persons. You can define your
+expection with concepts like so:
+
+```cpp
+template <typename T>
+concept person = requires(T p) {
+    std::string_view(p.name);  // has name field convertible to string_view
+    p.age;                     // has age field
+    requires std::is_integral_v<decltype(p.age)>;  // age is integral
+};
+
+/**
+ * Concept to validate that a type is an array of person objects
+ */
+template <typename T>
+concept array_of_person = requires(T arr) {
+    arr.size();                    // has size method
+    arr[0];                        // can access elements with []
+    requires person<decltype(arr[0])>;  // elements satisfy person concept
+};
+```
+
+And then a simple static assert with `decltype` is sufficient to check that the expectation is met:
+
+```cpp
+  constexpr auto config = R"(
+
+  [
+    { "name": "Alice", "age": 30 },
+    { "name": "Bob", "age": 25 },
+    { "name": "Charlie", "age": 35 }
+  ]
+
+  )"_json;
+
+
+  // Validate that the array satisfies the array_of_person concept
+  static_assert(array_of_person<decltype(config)>);
+```
+
+
+
+## Loading from disk
+
+In practice, you may have a JSON file, say `json_data` that you want to parse
+at compile time. You may do so as follows.
+
+```c++
+constexpr const char json_data[] = {
+    #embed "test.json"
+    , 0
+};
+
+constexpr auto json = simdjson::compile_time::parse_json<json_data>();
+```
+
+
+## Limitations (compile-time errors)
+
+We have a few limitations which trigger compile-time errors if violated.
+
+
+- Only JSON objects and arrays are supported at the top level (no primitives).
+  We will lift this limitation in the future.
+- Strings are represented using the `const char*` in UTF-8, but they must not
+  contain embedded nulls. We would prefer to represent them as std::string or
+  std::string_view, and hope to do so in the future.
+- Heterogeneous arrays are not supported yet. E.g., you need to have arrays of
+  all integers, or all strings, all floats, all compatible objects, etc.
+  For example, the following is accepted:
+  ```json
+   [
+    { "name": "Alice", "age": 30 },
+    { "name": "Bob", "age": 25 },
+    { "name": "Charlie", "age": 35 }
+  ]
+  ```
+  but the following is not:
+  ```json
+  [
+    { "name": "Alice", "age": 30 },
+    "Just a string",
+    42,
+    { "name": "Charlie", "age": 35 }
+  ]
+  ```
+  We may support heterogeneous arrays in the future with std::variant types.
+- We parse the first JSON document encountered in the string. Trailing
+  characters are ignored. Thus if your JSON begins with {"a":1}, everything
+  after the closing brace is ignored. This limitation will be lifted in the future,
+  reporting an error.
+
+These limitations are safe in the sense that they result in compile-time errors.
+Thus you will not get truncated strings or imprecise floats silently.
+
+
+Although we are committed to maintaining the functionality in the long run, the
+`compile_time::parse_json` function is subject to change.

doc/compile_time_accessors.md

@@ -0,0 +1,445 @@
+# Compile-Time JSONPath and JSON Pointer Accessors
+
+**Note:** This feature requires C++26 Static Reflection support (P2996) and is currently only available with experimental compilers. You must enable it with `-DSIMDJSON_STATIC_REFLECTION=ON` when building.
+
+## Overview
+
+simdjson provides compile-time JSONPath and JSON Pointer accessors that validate paths against struct definitions at compile time and generate optimized accessor code with zero runtime overhead. This combines the safety of compile-time type checking with the performance of pre-parsed, pre-validated access paths.
+
+## Requirements
+
+- C++26 compiler with Static Reflection support (P2996)
+- Experimental compiler flags:
+  - Clang with P2996 support: `-std=c++26 -freflection -fexpansion-statements`
+- Build configuration: `-DSIMDJSON_STATIC_REFLECTION=ON`
+
+## How It Works
+
+**Compile Time:**
+1. Path string is parsed and converted to access steps
+2. Path is validated against struct definition using reflection
+3. Field types are checked and verified
+4. Optimized accessor code is generated
+
+**Runtime:**
+- Direct navigation with no parsing
+- No validation overhead
+- No string comparisons for path components
+- Type-safe extraction
+
+## Two Usage Modes
+
+### Mode 1: With Type Validation (Recommended)
+
+When you provide a struct type, the compiler validates the entire path at compile time:
+
+```cpp
+struct User {
+  std::string name;
+  int age;
+  std::vector<std::string> emails;
+};
+
+//  R"( ... )" is a C++ raw string literal.
+const padded_string json = R"({
+  "name": "Alice",
+  "age": 30,
+  "emails": ["alice@example.com", "alice@work.com"]
+})"_padded;
+
+ondemand::parser parser;
+auto doc = parser.iterate(json);
+
+// Compile-time validation: checks that User has "name" field of type std::string
+std::string name;
+auto result = ondemand::json_path::at_path_compiled<User, ".name">(doc);
+result.get(name); // name = "Alice"
+
+// Compile-time validation: checks that "emails" is array-like with string elements
+std::string email;
+result = ondemand::json_path::at_path_compiled<User, ".emails[0]">(doc);
+result.get(email); // email = "alice@example.com"
+```
+
+**Benefits:**
+- **Compile-time errors** if path doesn't exist in struct
+- **Type safety** - verifies field types match expected types
+- **Refactoring protection** - renaming struct fields causes compile errors
+
+**What gets validated:**
+- Field existence
+- Field types
+- Array/container access validity
+- Nested struct navigation
+
+### Mode 2: Without Validation
+
+When you omit the struct type, the path is parsed at compile time but not validated:
+
+```cpp
+const padded_string json = R"({
+  "name": "Alice",
+  "age": 30,
+  "address": {"city": "Boston"}
+})"_padded;
+
+ondemand::parser parser;
+auto doc = parser.iterate(json);
+
+// No compile-time validation - path is only parsed
+std::string name;
+auto result = ondemand::json_path::at_path_compiled<".name">(doc);
+result.get(name); // name = "Alice"
+
+std::string_view city;
+result = ondemand::json_path::at_path_compiled<".address.city">(doc);
+result.get(city); // city = "Boston"
+```
+
+**Benefits:**
+- Works with dynamic/unknown JSON structures
+- Still benefits from compile-time path parsing
+- No runtime string parsing overhead
+
+**Use when:**
+- JSON structure is not known at compile time
+- Working with varied JSON schemas
+- Prototyping or exploratory parsing
+
+## JSONPath Syntax
+
+JSONPath uses dot notation and bracket notation for field access:
+
+### Supported Syntax
+
+| Syntax | Description | Example |
+|--------|-------------|---------|
+| `.field` | Dot notation for field access | `.name`, `.address.city` |
+| `["field"]` | Bracket notation with quotes | `["name"]`, `["address"]["city"]` |
+| `[index]` | Array index access | `[0]`, `[1]` |
+| Mixed | Combination of notations | `.emails[0]`, `["users"][0].name` |
+| `$` prefix | Optional root indicator | `$.name`, `$["name"]` |
+
+### Examples
+
+```cpp
+struct Address {
+  std::string city;
+  int zip;
+};
+
+struct Person {
+  std::string name;
+  int age;
+  Address address;
+  std::vector<std::string> emails;
+};
+
+// Dot notation
+at_path_compiled<Person, ".name">(doc)
+at_path_compiled<Person, ".address.city">(doc)
+
+// Bracket notation
+at_path_compiled<Person, "[\"name\"]">(doc)
+at_path_compiled<Person, "[\"address\"][\"city\"]">(doc)
+
+// Array access
+at_path_compiled<Person, ".emails[0]">(doc)
+at_path_compiled<Person, ".emails[1]">(doc)
+
+// Mixed notation
+at_path_compiled<Person, ".address[\"zip\"]">(doc)
+at_path_compiled<Person, "[\"emails\"][0]">(doc)
+
+// With root indicator
+at_path_compiled<Person, "$.name">(doc)
+at_path_compiled<Person, "$.address.city">(doc)
+```
+
+## JSON Pointer Syntax
+
+JSON Pointer (RFC 6901) uses slash-separated paths:
+
+### Supported Syntax
+
+| Syntax | Description | Example |
+|--------|-------------|---------|
+| `/field` | Field access | `/name`, `/address/city` |
+| `/index` | Array index | `/0`, `/1` |
+| `~0` | Escaped `~` | `/field~0name` → field~name |
+| `~1` | Escaped `/` | `/field~1name` → field/name |
+
+### Examples
+
+```cpp
+struct Car {
+  std::string make;
+  std::string model;
+  int64_t year;
+  std::vector<double> tire_pressure;
+};
+
+// Field access
+at_pointer_compiled<Car, "/make">(doc)
+at_pointer_compiled<Car, "/model">(doc)
+
+// Array access
+at_pointer_compiled<Car, "/tire_pressure/0">(doc)
+at_pointer_compiled<Car, "/tire_pressure/1">(doc)
+
+// Root pointer (returns whole document)
+at_pointer_compiled<Car, "">(doc)
+at_pointer_compiled<Car, "/">(doc)
+```
+
+## API Reference
+
+### JSONPath Functions
+
+```cpp
+// With type validation
+template<typename T, constevalutil::fixed_string Path, typename DocOrValue>
+simdjson_result<value> at_path_compiled(DocOrValue& doc_or_val);
+
+// Without validation
+template<constevalutil::fixed_string Path, typename DocOrValue>
+simdjson_result<value> at_path_compiled(DocOrValue& doc_or_val);
+```
+
+### JSON Pointer Functions
+
+```cpp
+// With type validation
+template<typename T, constevalutil::fixed_string Pointer, typename DocOrValue>
+simdjson_result<value> at_pointer_compiled(DocOrValue& doc_or_val);
+
+// Without validation
+template<constevalutil::fixed_string Pointer, typename DocOrValue>
+simdjson_result<value> at_pointer_compiled(DocOrValue& doc_or_val);
+```
+
+### Direct Field Extraction
+
+Extract values directly into variables with compile-time type checking:
+
+```cpp
+// JSONPath
+template<typename T, constevalutil::fixed_string Path>
+struct path_accessor {
+  template<typename DocOrValue, typename FieldType>
+  static error_code extract_field(DocOrValue& doc_or_val, FieldType& target);
+};
+
+// JSON Pointer
+template<typename T, constevalutil::fixed_string Pointer>
+struct pointer_accessor {
+  template<typename DocOrValue, typename FieldType>
+  static error_code extract_field(DocOrValue& doc_or_val, FieldType& target);
+};
+```
+
+**Example:**
+
+```cpp
+struct User {
+  std::string name;
+  int age;
+};
+
+ondemand::parser parser;
+auto doc = parser.iterate(json);
+
+// Extract directly into variable
+std::string name;
+ondemand::json_path::path_accessor<User, ".name">::extract_field(doc, name);
+
+int age;
+ondemand::json_path::pointer_accessor<User, "/age">::extract_field(doc, age);
+```
+
+The compiler verifies that the target variable type matches the field type at the path.
+
+## Complete Examples
+
+### Example 1: Validated Access
+
+```cpp
+#include "simdjson.h"
+using namespace simdjson;
+
+struct Car {
+  std::string make;
+  std::string model;
+  int64_t year;
+  std::vector<double> tire_pressure;
+};
+
+int main() {
+  const padded_string json = R"({
+    "make": "Toyota",
+    "model": "Camry",
+    "year": 2018,
+    "tire_pressure": [40.1, 39.9, 37.7, 40.4]
+  })"_padded;
+
+  ondemand::parser parser;
+  auto doc = parser.iterate(json);
+
+  // Type-validated access
+  std::string make;
+  auto result = ondemand::json_path::at_path_compiled<Car, ".make">(doc);
+  result.get(make); // make = "Toyota"
+
+  // Array access with validation
+  double pressure;
+  result = ondemand::json_path::at_path_compiled<Car, ".tire_pressure[1]">(doc);
+  result.get(pressure); // pressure = 39.9
+
+  return 0;
+}
+```
+
+### Example 2: Non-Validated Access
+
+```cpp
+#include "simdjson.h"
+using namespace simdjson;
+
+int main() {
+  const padded_string json = R"({
+    "user": {
+      "name": "Alice",
+      "preferences": {
+        "theme": "dark",
+        "notifications": true
+      }
+    }
+  })"_padded;
+
+  ondemand::parser parser;
+  auto doc = parser.iterate(json);
+
+  // No validation - works with any JSON structure
+  std::string_view theme;
+  auto result = ondemand::json_path::at_path_compiled<".user.preferences.theme">(doc);
+  result.get(theme); // theme = "dark"
+
+  bool notifications;
+  result = ondemand::json_path::at_path_compiled<".user.preferences.notifications">(doc);
+  result.get(notifications); // notifications = true
+
+  return 0;
+}
+```
+
+### Example 3: Direct Extraction
+
+```cpp
+#include "simdjson.h"
+using namespace simdjson;
+
+struct Person {
+  std::string name;
+  int age;
+  std::vector<std::string> emails;
+};
+
+int main() {
+  const padded_string json = R"({
+    "name": "Bob",
+    "age": 25,
+    "emails": ["bob@example.com", "bob@work.com"]
+  })"_padded;
+
+  ondemand::parser parser;
+  auto doc = parser.iterate(json);
+
+  // Extract with type validation
+  std::string name;
+  ondemand::json_path::path_accessor<Person, ".name">::extract_field(doc, name);
+  // name = "Bob"
+
+  int age;
+  ondemand::json_path::pointer_accessor<Person, "/age">::extract_field(doc, age);
+  // age = 25
+
+  std::string email;
+  ondemand::json_path::path_accessor<Person, ".emails[0]">::extract_field(doc, email);
+  // email = "bob@example.com"
+
+  return 0;
+}
+```
+
+## Error Handling
+
+Compile-time errors occur when:
+- Path doesn't exist in struct: `static_assert` failure
+- Field type mismatch: `static_assert` failure
+- Invalid array access on non-array field: `static_assert` failure
+
+Runtime errors occur when:
+- JSON structure doesn't match expected structure
+- Array index out of bounds
+- Type conversion failures
+
+```cpp
+struct User {
+  std::string name;
+  int age;
+};
+
+// Compile-time error: no "email" field in User
+// auto result = ondemand::json_path::at_path_compiled<User, ".email">(doc);
+
+// Compile-time error: age is not an array
+// auto result = ondemand::json_path::at_path_compiled<User, ".age[0]">(doc);
+
+// Runtime error if JSON doesn't have "name" field
+auto result = ondemand::json_path::at_path_compiled<User, ".name">(doc);
+std::string name;
+if (result.get(name) != SUCCESS) {
+  // Handle error
+}
+```
+
+## Performance
+
+Compile-time accessors provide:
+- **Zero path parsing overhead** - paths parsed at compile time
+- **Zero validation overhead** - validation done at compile time
+- **Direct field access** - no runtime path traversal
+- **Type-safe extraction** - no dynamic type checking
+
+Compared to runtime `at_path()` and `at_pointer()`:
+- Eliminates runtime path string parsing
+- Eliminates runtime path validation
+- Generates optimal code path directly
+
+## Limitations
+
+- Requires C++26 compiler with P2996 support (experimental)
+- Paths must be compile-time constants (string literals)
+- Cannot use runtime-computed paths
+- Limited to struct types that support reflection
+- Array indices must be compile-time constants in the path
+
+## When to Use
+
+**Use compile-time accessors when:**
+- You have well-defined struct types
+- JSON structure is known at compile time
+- You want maximum type safety
+- Performance is critical
+
+**Use runtime `at_path()`/`at_pointer()` when:**
+- JSON structure varies or is unknown
+- Paths are computed at runtime
+- Working with C++20 or earlier
+- Flexibility is more important than compile-time checks
+
+## See Also
+
+- [JSON Pointer](basics.md#json-pointer) - Runtime JSON Pointer support
+- [JSONPath](basics.md#jsonpath) - Runtime JSONPath support
+- [Static Reflection for Deserialization](basics.md#3-using-static-reflection-c26) - Using reflection for full struct deserialization

doc/dom.md

@@ -1,13 +1,18 @@
 The Document-Object-Model (DOM) front-end
 ==========
 
-An overview of what you need to know to use simdjson, with examples.
+An overview of what you need to know to use simdjson to parse JSON documents with
+our DOM API, with examples. [Our documentation regarding the generation (serialization) of JSON documents is in a
+separate document](https://github.com/simdjson/simdjson/blob/master/doc/builder.md).
 
-* [DOM vs On Demand](#dom-vs-on-demand)
+
+* [DOM vs On-Demand](#dom-vs-on-demand)
 * [The Basics: Loading and Parsing JSON Documents](#the-basics-loading-and-parsing-json-documents-using-the-dom-front-end)
 * [Using the Parsed JSON](#using-the-parsed-json)
 * [C++17 Support](#c17-support)
+* [C++20 Support](#c20-support)
 * [JSON Pointer](#json-pointer)
+* [JSONPath](#jsonpath)
 * [Error Handling](#error-handling)
   * [Error Handling Example](#error-handling-example)
   * [Exceptions](#exceptions)
@@ -18,7 +23,7 @@ An overview of what you need to know to use simdjson, with examples.
 * [Padding and Temporary Copies](#padding-and-temporary-copies)
 * [Performance Tips](#performance-tips)
 
-DOM vs On Demand
+DOM vs On-Demand
 ----------------------------------------------
 
 The simdjson library offers two distinct approaches on how to access a JSON document. We support
@@ -26,13 +31,17 @@ a conventional Document-Object-Model (DOM) front-end. In such a scenario, the JS
 entirely parsed, validated and materialized in memory as the first step. The programmer may
 then access the parsed data using this in-memory model.
 
+On-Demand is a different model where you parse just what you need, directly into your own
+data structure. The On-Demand approach, when well tuned, can provide superior performance.
+[We refer you to the On-Demand documentation for further details](https://github.com/simdjson/simdjson/blob/master/doc/basics.md).
+
 The Basics: Loading and Parsing JSON Documents using the DOM front-end
 ----------------------------------------------
 
 The simdjson library offers a simple DOM tree API, which you can access by creating a
 `dom::parser` and calling the `load()` method:
 
-```c++
+```cpp
 dom::parser parser;
 dom::element doc = parser.load(filename); // load and parse a file
 ```
@@ -40,25 +49,61 @@ dom::element doc = parser.load(filename); // load and parse a file
 Or by creating a padded string (for efficiency reasons, simdjson requires a string with
 SIMDJSON_PADDING bytes at the end) and calling `parse()`:
 
-```c++
+```cpp
 dom::parser parser;
 dom::element doc = parser.parse("[1,2,3]"_padded); // parse a string, the _padded suffix creates a simdjson::padded_string instance
 ```
 
+You can also load a `padded_string` from a file.
+
+
+```cpp
+auto json = padded_string::load("twitter.json"); // load JSON file 'twitter.json'.
+dom::element doc = parser.parse(json);
+```
+
+(Windows users compiling with C++17 or better may use `wchar_t` strings to support non-ASCII
+filenames: `padded_string::load(L"twitter.json")`.)
+
+
+(Windows users compiling with C++17 or better may use `wchar_t` strings to support non-ASCII
+filenames: `padded_string::load(L"twitter.json")`.)
+
+
 You can copy your data directly on a `simdjson::padded_string` as follows:
 
-```c++
+```cpp
 const char * data = "my data"; // 7 bytes
 simdjson::padded_string my_padded_data(data, 7); // copies to a padded buffer
 ```
 
 Or as follows...
 
-```c++
+```cpp
 std::string data = "my data";
 simdjson::padded_string my_padded_data(data); // copies to a padded buffer
 ```
 
+You can then parse the JSON document from the `simdjson::padded_string` instance:
+
+```cpp
+simdjson::dom::parser parser;
+simdjson::dom::element doc = parser.parse(my_padded_data);
+```
+
+Whenever you pass an `std::string` reference to `parser::parse`,
+the parser will access the bytes beyond the end of
+the string but before the end of the allocated memory (`std::string::capacity()`).
+If you are using a sanitizer that checks for reading uninitialized bytes or `std::string`'s
+container-overflow checks, you may encounter sanitizer warnings.
+You can safely ignore these warnings. Or you can call `simdjson::pad(std::string&)` to pad the
+string with `SIMDJSON_PADDING` spaces: this function returns a `simdjson::padding_string_view` which can be be passed to the parser's iterator function:
+
+```cpp
+std::string json = "[1]";
+dom::element doc = parser.parse(simdjson::pad(json));
+```
+
 The parsed document resulting from the `parser.load` and `parser.parse` calls depends on the `parser` instance. Thus the `parser` instance must remain in scope. Furthermore, you must have at most one parsed document in play per `parser` instance.
 You cannot copy a `parser` instance, you may only move it.
 
@@ -69,7 +114,7 @@ During the`load` or `parse` calls, neither the input file nor the input string a
 For best performance, a `parser` instance should be reused over several files: otherwise you will needlessly reallocate memory, an expensive process. It is also possible to avoid entirely memory allocations during parsing when using simdjson. [See our performance notes for details](performance.md).
 
 If you need a lower-level interface, you may call the function `parser.parse(const char * p, size_t l)` on a pointer `p` while specifying the
-length of your input `l` in bytes. To see how to get the very best performance from a low-level approach, you way want to read our [performance notes](https://github.com/simdjson/simdjson/blob/master/doc/performance.md#padding-and-temporary-copies) on this topic (see the Padding and Temporary Copies section).
+length of your input `l` in bytes.
 
 *Windows-specific*:  Windows users who need to read files with
 non-ANSI characters in the name should set their code page to
@@ -88,8 +133,9 @@ Once you have an element, you can navigate it with idiomatic C++ iterators, oper
   dom::object and dom::array. An exception (`simdjson::simdjson_error`) is thrown if the cast is not possible.
 * **Extracting Values (without exceptions):** You can use a variant usage of `get()` with error codes to avoid exceptions. You first declare the variable of the appropriate type (`double`, `uint64_t`, `int64_t`, `bool`, `std::string_view`,
   `dom::object` and `dom::array`) and pass it by reference to `get()` which gives you back an error code: e.g.,
-  ```c++
+  ```cpp
   simdjson::error_code error;
+  // _padded returns an simdjson::padded_string instance
   simdjson::padded_string numberstring = "1.2"_padded; // our JSON input ("1.2")
   simdjson::dom::parser parser;
   double value; // variable where we store the value to be parsed
@@ -98,6 +144,12 @@ Once you have an element, you can navigate it with idiomatic C++ iterators, oper
   std::cout << "I parsed " << value << " from " << numberstring.data() << std::endl;
   ```
   The strings contain unescaped valid UTF-8 strings: no unmatched surrogate is allowed.
+  Internally, numbers are stored as either 64-bit integers or 64-bit floating-point numbers.
+  Thus it is possible to get the full 64-bit integer range (either signed or  unsigned).
+  By default, the string `-0` is parsed as the integer 0 as in Python or C++. If you set the macro
+  `SIMDJSON_MINUS_ZERO_AS_FLOAT` to `1` when building simdjson, you can get that `-0` is mapped to `-0.0`
+  as in JavaScript. You can get the desired effect by building simdjson with cmake setting the
+  `SIMDJSON_MINUS_ZERO_AS_FLOAT` to on: `cmake -B build -D SIMDJSON_MINUS_ZERO_AS_FLOAT=ON`.
 * **Field Access:** To get the value of the "foo" field in an object, use `object["foo"]`.
 * **Array Iteration:** To iterate through an array, use `for (auto value : array) { ... }`. If you
   know the type of the value, you can cast it right there, too! `for (double value : array) { ... }`
@@ -117,7 +169,8 @@ Once you have an element, you can navigate it with idiomatic C++ iterators, oper
 
 The following code illustrates all of the above:
 
-```c++
+```cpp
+//  R"( ... )" is a C++ raw string literal.
 auto cars_json = R"( [
   { "make": "Toyota", "model": "Camry",  "year": 2018, "tire_pressure": [ 40.1, 39.9, 37.7, 40.4 ] },
   { "make": "Kia",    "model": "Soul",   "year": 2012, "tire_pressure": [ 30.1, 31.0, 28.6, 28.7 ] },
@@ -150,7 +203,7 @@ for (dom::object car : parser.parse(cars_json)) {
 
 Here is a different example illustrating the same ideas:
 
-```C++
+```cpp
 auto abstract_json = R"( [
     {  "12345" : {"a":12.34, "b":56.78, "c": 9998877}   },
     {  "12545" : {"a":11.44, "b":12.78, "c": 11111111}  }
@@ -172,7 +225,7 @@ for (dom::object obj : parser.parse(abstract_json)) {
 And another one:
 
 
-```C++
+```cpp
   auto abstract_json = R"(
     {  "str" : { "123" : {"abc" : 3.14 } } } )"_padded;
   dom::parser parser;
@@ -186,7 +239,7 @@ C++17 Support
 
 While the simdjson library can be used in any project using C++ 11 and above, field iteration has special support C++ 17's destructuring syntax. For example:
 
-```c++
+```cpp
 padded_string json = R"(  { "foo": 1, "bar": 2 }  )"_padded;
 dom::parser parser;
 dom::object object; // invalid until the get() succeeds
@@ -199,7 +252,7 @@ for (auto [key, value] : object) {
 
 For comparison, here is the C++ 11 version of the same code:
 
-```c++
+```cpp
 // C++ 11 version for comparison
 padded_string json = R"(  { "foo": 1, "bar": 2 }  )"_padded;
 dom::parser parser;
@@ -211,6 +264,23 @@ for (dom::key_value_pair field : object) {
 }
 ```
 
+C++20 Support
+------------
+
+simdjson library also supports some C++20 feature including `std::ranges`:
+
+```cpp
+auto cars_json = R"( [
+  { "make": "Toyota", "model": "Camry",  "year": 2018, "tire_pressure": [ 40.1, 39.9, 37.7, 40.4 ] },
+  { "make": "Kia",    "model": "Soul",   "year": 2012, "tire_pressure": [ 30.1, 31.0, 28.6, 28.7 ] },
+  { "make": "Toyota", "model": "Tercel", "year": 1999, "tire_pressure": [ 29.8, 30.0, 30.2, 30.5 ] }
+] )"_padded;
+dom::parser parser;
+auto justmodel = [](auto car) { return car["model"]; };
+for (auto car : parser.parse(cars_json).get_array() | std::views::transform(justmodel)) {
+  std::cout << car << std::endl;
+}
+```
 
 JSON Pointer
 ------------
@@ -218,7 +288,7 @@ JSON Pointer
 The simdjson library also supports [JSON pointer](https://tools.ietf.org/html/rfc6901) through the
 `at_pointer()` method, letting you reach further down into the document in a single call:
 
-```c++
+```cpp
 auto cars_json = R"( [
   { "make": "Toyota", "model": "Camry",  "year": 2018, "tire_pressure": [ 40.1, 39.9, 37.7, 40.4 ] },
   { "make": "Kia",    "model": "Soul",   "year": 2012, "tire_pressure": [ 30.1, 31.0, 28.6, 28.7 ] },
@@ -239,7 +309,7 @@ You can apply a JSON Pointer expression to any node and the path gets interprete
 
 Consider the following example:
 
-```c++
+```cpp
 auto cars_json = R"( [
   { "make": "Toyota", "model": "Camry",  "year": 2018, "tire_pressure": [ 40.1, 39.9, 37.7, 40.4 ] },
   { "make": "Kia",    "model": "Soul",   "year": 2012, "tire_pressure": [ 30.1, 31.0, 28.6, 28.7 ] },
@@ -257,15 +327,126 @@ for (dom::element car_element : cars) {
 }
 ```
 
+JSONPath
+------------
 
 
+The simdjson library supports a subset of [JSONPath](https://www.rfc-editor.org/rfc/rfc9535) (RFC 9535) through the `at_path()` method, allowing you to reach further into the document in a single call. The subset of JSONPath that is implemented is the subset that is trivially convertible into the JSON Pointer format, using `.` to access a field and `[]` to access a specific index.
+
+Consider the following example:
+
+```cpp
+auto cars_json = R"( [
+  { "make": "Toyota", "model": "Camry",  "year": 2018, "tire_pressure": [ 40.1, 39.9, 37.7, 40.4 ] },
+  { "make": "Kia",    "model": "Soul",   "year": 2012, "tire_pressure": [ 30.1, 31.0, 28.6, 28.7 ] },
+  { "make": "Toyota", "model": "Tercel", "year": 1999, "tire_pressure": [ 29.8, 30.0, 30.2, 30.5 ] }
+] )"_padded;
+dom::parser parser;
+dom::element doc;
+auto error = parser.parse(cars_json).get(doc);
+if(error) { /*won't happen*/ }
+double p;
+error = doc.at_path("[0].tire_pressure[1]").get(p);
+if(error) { /*won't happen*/ }
+cout << p << endl; // Prints 39.9
+```
+
+
+We also support the `$` prefix. When you start a JSONPath expression with $, you are indicating that the path starts from the root of the JSON document. E.g.,
+
+```cpp
+auto json = R"( { "c" :{ "foo": { "a": [ 10, 20, 30 ] }}, "d": { "foo2": { "a": [ 10, 20, 30 ] }} , "e": 120 })"_padded;
+dom::parser parser;
+dom::element doc;
+auto error = parser.parse(json).get(doc);
+if(error) { /*won't happen*/ }
+dom::object obj;
+error = doc.get_object().get(obj);
+if(error) { /*won't happen*/ }
+int64_t x;
+error = obj.at_path("$[3].foo.a[1]").get(x);
+if(error) { /*won't happen*/ }
+if(x != 20) { /*won't happen*/ }
+x = obj.at_path("$.d.foo2.a.2");
+if(error) { /*won't happen*/ }
+```
+
+
+## Using `at_path_with_wildcard` for JSONPath Queries
+
+The `at_path_with_wildcard` function in simdjson extends the JSONPath querying capabilities by supporting wildcard expressions (`*`) in JSON paths. This allows users to retrieve multiple elements from a JSON document in a single query. For example, you can use `$.address.*` to fetch all fields within the `address` object or `$.phoneNumbers[*].numbers[*]` to retrieve all phone numbers across multiple objects in an array.
+
+The `*` wildcard matches all elements at a specific level. For instance, `$.address.*` retrieves all key-value pairs in the `address` object, while `$.*.streetAddress` fetches all `streetAddress` fields across objects at the root level.  You can combine wildcards with array indexing. For example, `$.phoneNumbers[*].numbers[1]` retrieves the second number from each `numbers` array in the `phoneNumbers` array. If no elements match the wildcard query, the function returns an empty result. For instance, querying `$.empty_object.*` or `$.empty_array.*` will yield an empty set.
+
+### Example Usage
+
+Here is an example demonstrating the use of `at_path_with_wildcard`:
+
+```cpp
+simdjson::padded_string json_string = R"(
+{
+  "firstName": "John",
+  "lastName": "doe",
+  "age": 26,
+  "address": {
+    "streetAddress": "naist street",
+    "city": "Nara",
+    "postalCode": "630-0192"
+  },
+  "phoneNumbers": [
+    {
+      "type": "iPhone",
+      "numbers": ["0123-4567-8888", "0123-4567-8788"]
+    },
+    {
+      "type": "home",
+      "numbers": ["0123-4567-8910"]
+    }
+  ]
+})"_padded;
+
+dom::parser parser;
+dom::element parsed_json = parser.parse(json_string);
+std::vector<dom::element> values;
+
+// Fetch all fields in the address object
+auto error = parsed_json.at_path_with_wildcard("$.address.*").get(values);
+if(error) {
+  // do something
+}
+for (auto &value : values) {
+  std::string_view field;
+  error = value.get(field);
+  if(error) {
+    // do something
+  }
+  std::cout << field << std::endl;
+}
+
+// Fetch all phone numbers
+error = parsed_json.at_path_with_wildcard("$.phoneNumbers[*].numbers[*]").get(values);
+if(error) {
+  // do something
+}
+for (auto &value : values) {
+  std::string_view number;
+  error = value.get(number);
+  if(error) {
+    // do something
+  }
+  std::cout << number << std::endl;
+}
+```
+
+This function is particularly useful for extracting data from complex JSON structures with nested arrays and objects. By leveraging wildcards, you can simplify your queries and reduce the need for multiple iterations.
+
 Error Handling
 --------------
 
 All simdjson APIs that can fail return `simdjson_result<T>`, which is a &lt;value, error_code&gt;
 pair. You can retrieve the value with .get(), like so:
 
-```c++
+```cpp
 dom::element doc;
 auto error = parser.parse(json).get(doc);
 if (error) { cerr << error << endl; exit(1); }
@@ -299,7 +480,7 @@ We can write a "quick start" example where we attempt to parse the following JSO
 Our program loads the file, selects value corresponding to key "search_metadata" which expected to be an object, and then
 it selects the key "count" within that object.
 
-```C++
+```cpp
 #include <iostream>
 #include "simdjson.h"
 
@@ -327,7 +508,7 @@ triggering exceptions. To do this, we use `["statuses"].at(0)["id"]`. We break t
 
 Observe how we use the `at` method when querying an index into an array, and not the bracket operator.
 
-```C++
+```cpp
 #include <iostream>
 #include "simdjson.h"
 
@@ -351,7 +532,7 @@ over the content of an array.
 
 This is how the example in "Using the Parsed JSON" could be written using only error code checking:
 
-```c++
+```cpp
 auto cars_json = R"( [
   { "make": "Toyota", "model": "Camry",  "year": 2018, "tire_pressure": [ 40.1, 39.9, 37.7, 40.4 ] },
   { "make": "Kia",    "model": "Soul",   "year": 2012, "tire_pressure": [ 30.1, 31.0, 28.6, 28.7 ] },
@@ -398,7 +579,7 @@ for (dom::element car_element : cars) {
 
 Here is another example:
 
-```C++
+```cpp
 auto abstract_json = R"( [
     {  "12345" : {"a":12.34, "b":56.78, "c": 9998877}   },
     {  "12545" : {"a":11.44, "b":12.78, "c": 11111111}  }
@@ -431,7 +612,7 @@ for (dom::element elem : array) {
 
 And another one:
 
-```C++
+```cpp
   auto abstract_json = R"(
     {  "str" : { "123" : {"abc" : 3.14 } } } )"_padded;
   dom::parser parser;
@@ -445,7 +626,7 @@ Notice how we can string several operations (`parser.parse(abstract_json)["str"]
 
 The next two functions will take as input a JSON document containing an array with a single element, either a string or a number. They return true upon success.
 
-```C++
+```cpp
 simdjson::dom::parser parser{};
 
 bool parse_double(const char *j, double &d) {
@@ -477,7 +658,7 @@ target_compile_definitions(simdjson PUBLIC SIMDJSON_EXCEPTIONS=OFF)
 
 Users more comfortable with an exception flow may choose to directly cast the `simdjson_result<T>` to the desired type:
 
-```c++
+```cpp
 dom::element doc = parser.parse(json); // Throws an exception if there was an error!
 ```
 
@@ -487,7 +668,7 @@ program from continuing if there was an error.
 
 If one is willing to trigger exceptions, it is possible to write simpler code:
 
-```C++
+```cpp
 #include <iostream>
 #include "simdjson.h"
 
@@ -508,7 +689,7 @@ inspect or walk over JSON elements. To do that, you can use iterators and the ty
 example, here's a quick and dirty recursive function that verbosely prints the JSON document as JSON
 (* ignoring nuances like trailing commas and escaping strings, for brevity's sake):
 
-```c++
+```cpp
 void print_json(dom::element element) {
   switch (element.type()) {
     case dom::element_type::ARRAY:
@@ -564,7 +745,7 @@ and reuse it. The simdjson library will allocate and retain internal buffers bet
 buffers hot in cache and keeping memory allocation and initialization to a minimum. In this manner,
 you can parse terabytes of JSON data without doing any new allocation.
 
-```c++
+```cpp
 dom::parser parser;
 
 // This initializes buffers and a document big enough to handle this JSON.
@@ -607,7 +788,7 @@ without bound:
 
 * You can set a *max capacity* when constructing a parser:
 
-  ```c++
+  ```cpp
   dom::parser parser(1000*1000); // Never grow past documents > 1MB
   for (web_request request : listen()) {
     dom::element doc;
@@ -623,7 +804,7 @@ without bound:
 * You can set a *fixed capacity* that never grows, as well, which can be excellent for
   predictability and reliability, since simdjson will never call malloc after startup!
 
-  ```c++
+  ```cpp
   dom::parser parser(0); // This parser will refuse to automatically grow capacity
   auto error = parser.allocate(1000*1000); // This allocates enough capacity to handle documents <= 1MB
   if (error) { cerr << error << endl; exit(1); }
@@ -654,7 +835,7 @@ When calling `parser.parse` on a pointer (e.g., `parser.parse(my_char_pointer, m
 Some users may not be able use our `padded_string` class or to load the data directly from disk (`parser.load`). They may need to pass data pointers to the library.  If these users wish to avoid temporary copies and corresponding temporary memory allocations, they may want to call `parser.parse` with the `realloc_if_needed` parameter set to false (e.g., `parser.parse(my_char_pointer, my_length_in_bytes, false)`). In such cases, they need to ensure that there are at least SIMDJSON_PADDING extra bytes at the end that can be safely accessed and read. They do not need to initialize the padded bytes to any value in particular. The following example is safe:
 
 
-```C++
+```cpp
 const char *json      = R"({"key":"value"})";
 const size_t json_len = std::strlen(json);
 std::unique_ptr<char[]> padded_json_copy{new char[json_len + SIMDJSON_PADDING]};
@@ -662,12 +843,12 @@ memcpy(padded_json_copy.get(), json, json_len);
 memset(padded_json_copy.get() + json_len, 0, SIMDJSON_PADDING);
 simdjson::dom::parser parser;
 simdjson::dom::element element = parser.parse(padded_json_copy.get(), json_len, false);
-````
+```
 
 Setting the `realloc_if_needed` parameter `false` in this manner may lead to better performance since copies are avoided, but it requires that the user takes more responsibilities: the simdjson library cannot verify that the input buffer was padded with SIMDJSON_PADDING extra bytes.
 
 Performance Tips
 ---------------------
 
-- For release builds, we recommend setting `NDEBUG` pre-processor directive when compiling the `simdjson` library. Importantly, using the optimization flags `-O2` or `-O3` under GCC and LLVM clang does not set the `NDEBUG` directrive, you must set it manually (e.g., `-DNDEBUG`).
+- For release builds, we recommend setting `NDEBUG` pre-processor directive when compiling the `simdjson` library. Importantly, using the optimization flags `-O2` or `-O3` under GCC and LLVM clang does not set the `NDEBUG` directive, you must set it manually (e.g., `-DNDEBUG`).
 - For long streams of JSON documents, consider [`iterate_many`](iterate_many.md) and [`parse_many`](parse_many.md) for better performance.

doc/implementation-selection.md

@@ -55,7 +55,7 @@ Inspecting the Detected Implementation
 
 You can check what implementation is running with `active_implementation`:
 
-```c++
+```cpp
 cout << "simdjson v" << SIMDJSON_VERSION << endl;
 cout << "Detected the best implementation for your machine: " << simdjson::get_active_implementation()->name();
 cout << "(" << simdjson::get_active_implementation()->description() << ")" << endl;
@@ -68,7 +68,7 @@ Querying Available Implementations
 
 You can list all available implementations, regardless of which one was selected:
 
-```c++
+```cpp
 for (auto implementation : simdjson::get_available_implementations()) {
   cout << implementation->name() << ": " << implementation->description() << endl;
 }
@@ -76,7 +76,7 @@ for (auto implementation : simdjson::get_available_implementations()) {
 
 And look them up by name:
 
-```c++
+```cpp
 cout << simdjson::get_available_implementations()["fallback"]->description() << endl;
 ```
 When an implementation is not available, the bracket call `simdjson::get_available_implementations()[name]`
@@ -93,7 +93,7 @@ Manually Selecting the Implementation
 If you're trying to do performance tests or see how different implementations of simdjson run, you
 can select the CPU architecture yourself:
 
-```c++
+```cpp
 // Use the fallback implementation, even though my machine is fast enough for anything
 simdjson::get_active_implementation() = simdjson::get_available_implementations()["fallback"];
 ```
@@ -102,7 +102,7 @@ You are responsible for ensuring that the requirements of the selected implement
 Furthermore, you should check that the implementation is available before setting it to `simdjson::get_active_implementation()`
 by comparing it with the null pointer.
 
-```c++
+```cpp
 auto my_implementation = simdjson::get_available_implementations()["haswell"];
 if (! my_implementation) { exit(1); }
 if (! my_implementation->supported_by_runtime_system()) { exit(1); }
@@ -114,7 +114,7 @@ Checking that an Implementation can Run on your System
 
 You should call `supported_by_runtime_system()` to compare the processor's features with the need of the implementation.
 
-```c++
+```cpp
 for (auto implementation : simdjson::get_available_implementations()) {
   if (implementation->supported_by_runtime_system()) {
     cout << implementation->name() << ": " << implementation->description() << endl;

doc/iterate_many.md

@@ -8,7 +8,7 @@ library provides high-speed access to files or streams containing multiple small
 {"text":"a"}
 {"text":"b"}
 {"text":"c"}
-...
+"..."
 ```
 ... you want to read the entries (individual JSON documents) as quickly and as conveniently as possible. Importantly, the input might span several gigabytes, but you want to use a small (fixed) amount of memory. Ideally, you'd also like the parallelize the processing (using more than one core) to speed up the process.
 
@@ -25,6 +25,7 @@ Contents
 - [Use cases](#use-cases)
 - [Tracking your position](#tracking-your-position)
 - [Incomplete streams](#incomplete-streams)
+- [C++20 features](#c20-features)
 
 Motivation
 -----------
@@ -102,7 +103,12 @@ remove almost entirely its cost and replaces it by the overhead of a thread, whi
 cheaper. Ain't that awesome!
 
 Thread support is only active if thread supported is detected in which case the macro
-SIMDJSON_THREADS_ENABLED is set. Otherwise the library runs in  single-thread mode.
+SIMDJSON_THREADS_ENABLED is set.  You can also manually pass `SIMDJSON_THREADS_ENABLED=1` flag
+to the library. Otherwise the library runs in single-thread mode.
+
+You should be consistent. If you link against the simdjson library built for multithreading
+(i.e., with `SIMDJSON_THREADS_ENABLED`), then you should build your application with multithreading
+system (setting `SIMDJSON_THREADS_ENABLED=1` and linking against a thread library).
 
 A `document_stream` instance uses at most two threads: there is a main thread and a worker thread.
 
@@ -124,9 +130,9 @@ If your documents are all objects or arrays, then you may even have nothing betw
 E.g., `[1,2]{"32":1}` is recognized as two documents.
 
 Some official formats **(non-exhaustive list)**:
-- [Newline-Delimited JSON (NDJSON)](http://ndjson.org/)
+- [Newline-Delimited JSON (NDJSON)](https://github.com/ndjson/ndjson-spec/)
 - [JSON lines (JSONL)](http://jsonlines.org/)
-- [Record separator-delimited JSON (RFC 7464)](https://tools.ietf.org/html/rfc7464) <- Not supported by JsonStream!
+- [Record separator-delimited JSON (RFC 7464)](https://tools.ietf.org/html/rfc7464) <- Not supported by simdjson!
 - [More on Wikipedia...](https://en.wikipedia.org/wiki/JSON_streaming)
 
 API
@@ -134,8 +140,10 @@ API
 
 Example:
 
-```c++
+```cpp
+//  R"( ... )" is a C++ raw string literal.
 auto json = R"({ "foo": 1 } { "foo": 2 } { "foo": 3 } )"_padded;
+// _padded returns an simdjson::padded_string instance
 ondemand::parser parser;
 ondemand::document_stream docs = parser.iterate_many(json);
 for (auto doc : docs) {
@@ -191,7 +199,7 @@ and `error()` to check if there were any error.
 Let us illustrate the idea with code:
 
 
-```C++
+```cpp
     auto json = R"([1,2,3]  {"1":1,"2":3,"4":4} [1,2,3]  )"_padded;
     simdjson::ondemand::parser parser;
     simdjson::ondemand::document_stream stream;
@@ -232,7 +240,7 @@ Some users may need to work with truncated streams. The simdjson may truncate do
 
 Consider the following example where a truncated document (`{"key":"intentionally unclosed string  `) containing 39 bytes has been left within the stream. In such cases, the first two whole documents are parsed and returned, and the `truncated_bytes()` method returns 39.
 
-```C++
+```cpp
     auto json = R"([1,2,3]  {"1":1,"2":3,"4":4} {"key":"intentionally unclosed string  )"_padded;
     simdjson::ondemand::parser parser;
     simdjson::ondemand::document_stream stream;
@@ -261,7 +269,7 @@ is effectively ignored, as it is set to at least the document size.
 
 Example:
 
-```C++
+```cpp
     auto json = R"( 1, 2, 3, 4, "a", "b", "c", {"hello": "world"} , [1, 2, 3])"_padded;
     ondemand::parser parser;
     ondemand::document_stream doc_stream;
@@ -288,3 +296,111 @@ string
 object
 array
 ```
+
+
+C++20 features
+--------------------
+
+In C++20, the standard introduced the notion of *customization point*.
+A customization point is a function or function object that can be customized for different types. It allows library authors to provide default behavior while giving users the ability to override this behavior for specific types.
+
+A tag_invoke function serves as a mechanism for customization points. It is not directly part of the C++ standard library but is often used in libraries that implement customization points.
+The tag_invoke function is typically a generic function that takes a tag type and additional arguments.
+The first argument is usually a tag type (often an empty struct) that uniquely identifies the customization point (e.g., deserialization of custom types in simdjson). Users or library providers can specialize tag_invoke for their types by defining it in the appropriate namespace, often inline namespace.
+
+
+
+You can deserialize you own data structures conveniently if your system supports C++20.
+When it is the case, the macro `SIMDJSON_SUPPORTS_CONCEPTS` will be set to 1 by
+the simdjson library.
+
+Consider a custom class `Car`:
+
+```cpp
+struct Car {
+  std::string make;
+  std::string model;
+  int year;
+  std::vector<float> tire_pressure;
+};
+```
+
+
+You may support deserializing directly from a JSON value or document to your own `Car` instance
+by defining a single `tag_invoke` function:
+
+
+```cpp
+namespace simdjson {
+// This tag_invoke MUST be inside simdjson namespace
+template <typename simdjson_value>
+auto tag_invoke(deserialize_tag, simdjson_value &val, Car& car) {
+  ondemand::object obj;
+  auto error = val.get_object().get(obj);
+  if (error) {
+    return error;
+  }
+  if ((error = obj["make"].get_string(car.make))) {
+    return error;
+  }
+  if ((error = obj["model"].get_string(car.model))) {
+    return error;
+  }
+  if ((error = obj["year"].get(car.year))) {
+    return error;
+  }
+  if ((error = obj["tire_pressure"].get<std::vector<float>>().get(
+           car.tire_pressure))) {
+    return error;
+  }
+  return simdjson::SUCCESS;
+}
+} // namespace simdjson
+```
+
+Importantly, the `tag_invoke` function must be inside the `simdjson` namespace.
+Let us explain each argument of `tag_invoke` function.
+
+- `simdjson::deserialize_tag`: it is the tag for Customization Point Object (CPO). You may often ignore this parameter. It is used to indicate that you mean to provide a deserialization function for simdjson.
+- `var`: It receives automatically a `simdjson` value type (document, value, document_reference).
+- The third parameter is an instance of the type that you want to support.
+
+Please see our main documentation (`basics.md`) under
+"Use `tag_invoke` for custom types (C++20)" for details about
+tag_invoke functions.
+
+Given a stream of JSON documents, you can add them to a data structure
+such as a `std::vector<Car>` like so if you support exceptions:
+
+```cpp
+  padded_string json =
+      R"( { "make": "Toyota", "model": "Camry",  "year": 2018,
+       "tire_pressure": [ 40.1, 39.9 ] }
+  { "make": "Kia",    "model": "Soul",   "year": 2012,
+       "tire_pressure": [ 30.1, 31.0 ] }
+  { "make": "Toyota", "model": "Tercel", "year": 1999,
+       "tire_pressure": [ 29.8, 30.0 ] }
+)"_padded;
+  ondemand::parser parser;
+  ondemand::document_stream stream;
+  [[maybe_unused]] auto error = parser.iterate_many(json).get(stream);
+  std::vector<Car> cars;
+  for(auto doc : stream) {
+    cars.push_back((Car)doc); // an exception may be thrown
+  }
+```
+
+Otherwise you may use this longer version for explicit handling of errors:
+
+
+```cpp
+  std::vector<Car> cars;
+  for(auto doc : stream) {
+    Car c;
+    if ((error = doc.get<Car>().get(c))) {
+      std::cerr << simdjson::error_message(error); << std::endl;
+      return EXIT_FAILURE;
+    }
+    cars.push_back(c);
+  }
+```