4.4.2

#2617 introduced an RVV check that only checks if the compiler supports RVV intrinsics without checking if RVV is enabled at compile time.

This has caused compilation failure of node.js on riscv64. Fix it by appending a check for __riscv_vector.

.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

.github/ISSUE_TEMPLATE/bug_report.md

@@ -29,6 +29,9 @@ We accept the identification of an issue by a sanitizer or some checker tool (e.
 
 We recommend that you run your tests using different optimization levels. In particular, we recommend your run tests with the simdjson library and you code compiled in debug mode. The simdjson then sets the SIMDJSON_DEVELOPMENT_CHECKS macro to 1, and this triggers additional checks on your code and on the internals of the library. If possible, we recommend that you run tests with sanitizers (e.g., see [No more leaks with sanitize flags in gcc and clang](https://lemire.me/blog/2016/04/20/no-more-leaks-with-sanitize-flags-in-gcc-and-clang/)).  You can compile the library with sanitizers for debugging purposes (e.g., set SIMDJSON_SANITIZE to ON using CMake), but you should also turn on sanitizers on your own code. You may also use tools like valgrind or the commercial equivalent.
 
+Mixing debug and release simdjson code is unsafe: you either build all your code using simdjson in
+release mode or all of it in debug mode.
+
 Before reporting a bug, please ensure that you have read our documentation.
 
 **To Reproduce**
@@ -38,7 +41,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 +58,7 @@ We support up-to-date 64-bit ARM and x64 FreeBSD, macOS, Windows and Linux syste
 * We do not support unreleased or experimental compilers. If you encounter an issue with a
 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.
+* Vendors (e.g., Apple and Microsoft) stop supporting old systems. Once a compiler system is no longer supported by its vendor, we no longer support it. We will gladly accept code contributions, but we do not consider it a *bug* if you have issues with an obsolete compiler systems. This policy extends to obsolete standard libraries, linkers and other build tools. Please do not report it as an issue. If you cannot resolve the issue yourself, we encourage you to reach out to the vendor for legacy support.
 
 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).
 

.github/pull_request_template.md

@@ -6,6 +6,7 @@ Description
 
 Type of change
 - [ ] Bug fix
+- [ ] Optimization
 - [ ] New feature
 - [ ] Refactor / cleanup
 - [ ] Documentation / tests
@@ -19,7 +20,7 @@ How to verify / test
 Please read before contributing:
 - CONTRIBUTING: https://github.com/simdjson/simdjson/blob/master/CONTRIBUTING.md
 - HACKING: https://github.com/simdjson/simdjson/blob/master/HACKING.md
-
+- AI Usage Policy: https://github.com/simdjson/simdjson/blob/master/AI_USAGE_POLICY.md
 
 
 If you can, we recommend running our tests with the sanitizers turned on.

.github/workflows/documentation.yml

@@ -2,7 +2,13 @@ name: Doxygen GitHub Pages
 
 on:
   release:
-    types: [created]
+    # 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:
+    tags:
+      - "v*"  # common release tag pattern like v1.2.3
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 
@@ -27,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/rvv-1024-clang-18.yml

@@ -19,11 +19,11 @@ jobs:
         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)
+        CC=clang-18 CXX=clang++-18 CFLAGS="--target=riscv64-linux-gnu -march=rv64gcv_zvbb" CXXFLAGS="${CFLAGS}" \
+        cmake --toolchain=cmake/toolchains-ci/riscv64-linux-gnu.cmake -DSIMDJSON_DEVELOPER_MODE=ON -B build
+        cmake --build build/ -j$(nproc) --config Release
     - 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"
+        QEMU_LD_PREFIX="/usr/riscv64-linux-gnu" \
+        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

@@ -19,11 +19,6 @@ jobs:
         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)
+        CC=clang-17 CXX=clang++-17 CFLAGS="--target=riscv64-linux-gnu -march=rv64gcv" CXXFLAGS="${CFLAGS}" \
+        cmake --toolchain=cmake/toolchains-ci/riscv64-linux-gnu.cmake -DSIMDJSON_DEVELOPER_MODE=ON -B build
+        cmake --build build/ -j$(nproc) --config Release

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

@@ -0,0 +1,39 @@
+name: Ubuntu rvv VLEN=128 (clang 20)
+
+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-20
+    - name: Build
+      run: |
+        CC=clang-20 CXX=clang++-20 CFLAGS="--target=riscv64-linux-gnu -march=rv64gcv" CXXFLAGS="${CFLAGS}" \
+        cmake --toolchain=cmake/toolchains-ci/riscv64-linux-gnu.cmake -DSIMDJSON_DEVELOPER_MODE=ON -B build
+        cmake --build build/ -j$(nproc) --config Release
+    - name: Test VLEN=128
+      run: |
+        QEMU_LD_PREFIX="/usr/riscv64-linux-gnu" \
+        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)
+    - name: Build VLS
+      run: |
+        CC=clang-20 CXX=clang++-20 CFLAGS="--target=riscv64-linux-gnu -march=rv64gcv_zvl128b_zba_zbb_zbc -mrvv-vector-bits=zvl" CXXFLAGS="${CFLAGS}" \
+        cmake --toolchain=cmake/toolchains-ci/riscv64-linux-gnu.cmake -DSIMDJSON_DEVELOPER_MODE=ON -B build-vls
+        cmake --build build-vls/ -j$(nproc) --config Release
+    - name: Test VLEN=128 VLS
+      run: |
+        QEMU_LD_PREFIX="/usr/riscv64-linux-gnu" \
+        QEMU_CPU="rv64,v=on,zba=on,zbb=on,zbc=on,vlen=128,rvv_ta_all_1s=on,rvv_ma_all_1s=on" \
+        ctest --timeout 1800 --output-on-failure --test-dir build-vls -j $(nproc)

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

@@ -19,11 +19,21 @@ jobs:
         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)
+        CC=riscv64-linux-gnu-gcc-14 CXX=riscv64-linux-gnu-g++-14 CFLAGS=-march=rv64gcv CXXFLAGS="${CFLAGS}" \
+        cmake --toolchain=cmake/toolchains-ci/riscv64-linux-gnu.cmake -DSIMDJSON_DEVELOPER_MODE=ON -B build
+        cmake --build build/ -j$(nproc) --config Release
     - 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"
+        QEMU_LD_PREFIX="/usr/riscv64-linux-gnu" \
+        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)
+    - name: Build VLS
+      run: |
+        CC=riscv64-linux-gnu-gcc-14 CXX=riscv64-linux-gnu-g++-14 CFLAGS="-march=rv64gcv_zvl256b -mrvv-vector-bits=zvl" CXXFLAGS="${CFLAGS}" \
+        cmake --toolchain=cmake/toolchains-ci/riscv64-linux-gnu.cmake -DSIMDJSON_DEVELOPER_MODE=ON -B build-vls
+        cmake --build build-vls/ -j$(nproc) --config Release
+    - name: Test VLEN=256 VLS
+      run: |
+        QEMU_LD_PREFIX="/usr/riscv64-linux-gnu" \
+        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-vls -j $(nproc)

.github/workflows/rvv-512-clang-19.yml

@@ -0,0 +1,39 @@
+name: Ubuntu rvv VLEN=512 (clang 19)
+
+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-19
+    - name: Build
+      run: |
+        CC=clang-19 CXX=clang++-19 CFLAGS="--target=riscv64-linux-gnu -march=rv64gcv" CXXFLAGS="${CFLAGS}" \
+        cmake --toolchain=cmake/toolchains-ci/riscv64-linux-gnu.cmake -DSIMDJSON_DEVELOPER_MODE=ON -B build
+        cmake --build build/ -j$(nproc) --config Release
+    - name: Test VLEN=512
+      run: |
+        QEMU_LD_PREFIX="/usr/riscv64-linux-gnu" \
+        QEMU_CPU="rv64,v=on,vlen=512,rvv_ta_all_1s=on,rvv_ma_all_1s=on" \
+        ctest --timeout 1800 --output-on-failure --test-dir build -j $(nproc)
+    - name: Build VLS
+      run: |
+        CC=clang-19 CXX=clang++-19 CFLAGS="--target=riscv64-linux-gnu -march=rv64gcv_zvl512b_zba_zbb_zbc -mrvv-vector-bits=zvl" CXXFLAGS="${CFLAGS}" \
+        cmake --toolchain=cmake/toolchains-ci/riscv64-linux-gnu.cmake -DSIMDJSON_DEVELOPER_MODE=ON -B build-vls
+        cmake --build build-vls/ -j$(nproc) --config Release
+    - name: Test VLEN=512 VLS
+      run: |
+        QEMU_LD_PREFIX="/usr/riscv64-linux-gnu" \
+        QEMU_CPU="rv64,v=on,zba=on,zbb=on,zbc=on,vlen=512,rvv_ta_all_1s=on,rvv_ma_all_1s=on" \
+        ctest --timeout 1800 --output-on-failure --test-dir build-vls -j $(nproc)

.github/workflows/ubuntu24-checkperf.yml

@@ -1,4 +1,4 @@
-name: Performance check on Ubuntu 20.04 CI (GCC 9)
+name: Performance check on Ubuntu 24.04 CI (GCC 13)
 
 on:
   push:

.github/workflows/ubuntu24-noexcept.yml

@@ -1,4 +1,4 @@
-name: Ubuntu 20.04 CI (GCC 9) without exceptions
+name: Ubuntu 24.04 CI (GCC 13) without exceptions
 
 on: [push, pull_request]
 
@@ -24,7 +24,7 @@ jobs:
           cd .. &&
           mkdir build &&
           cd build &&
-          cmake  -DSIMDJSON_DEVELOPER_MODE=ON -DSIMDJSON_GOOGLE_BENCHMARKS=ON -DSIMDJSON_GOOGLE_BENCHMARKS=ON -DSIMDJSON_EXCEPTIONS=OFF -DBUILD_SHARED_LIBS=OFF -DCMAKE_INSTALL_PREFIX:PATH=destination ..  &&
+          cmake  -DSIMDJSON_DEVELOPER_MODE=ON -DSIMDJSON_GOOGLE_BENCHMARKS=ON -DSIMDJSON_EXCEPTIONS=OFF -DBUILD_SHARED_LIBS=OFF -DCMAKE_INSTALL_PREFIX:PATH=destination ..  &&
           cmake --build .   &&
           ctest --output-on-failure -LE explicitonly -j   &&
           make install  &&

.github/workflows/ubuntu24-nothread.yml

@@ -1,4 +1,4 @@
-name: Ubuntu 20.04 CI (GCC 9) Without Threads
+name: Ubuntu 24.04 CI (GCC 13) Without Threads
 
 on: [push, pull_request]
 

.github/workflows/ubuntu24-sani.yml

@@ -1,9 +1,9 @@
-name: Ubuntu 20.04 CI (GCC 9) With Memory Sanitizer
+name: Ubuntu 24.04 CI (GCC 13) With Memory Sanitizer
 
 on: [push, pull_request]
 
 jobs:
-  ubuntu-build-address-sanitizier:
+  ubuntu-build-address-sanitizer:
     if: >-
       ! contains(toJSON(github.event.commits.*.message), '[skip ci]') &&
       ! contains(toJSON(github.event.commits.*.message), '[skip github]')

AI_USAGE_POLICY.md

@@ -0,0 +1,56 @@
+# AI Usage Policy
+
+Contributors can use whatever tools they would like to
+craft their contributions, but there must be a **human in the loop**.
+**Contributors must read and review all LLM-generated code or text before they
+ask other project members to review it.** The contributor is always the author
+and is fully accountable for their contributions. Contributors should be
+sufficiently confident that the contribution is high enough quality that asking
+for a review is a good use of scarce maintainer time, and they should be **able
+to answer questions about their work** during review.
+
+We expect that new contributors will be less confident in their contributions,
+and our guidance to them is to **start with small contributions** that they can
+fully understand to build confidence. We aspire to be a welcoming community
+that helps new contributors grow their expertise, but learning involves taking
+small steps, getting feedback, and iterating. Passing maintainer feedback to an
+LLM doesn't help anyone grow, and does not sustain our community.
+
+This policy includes, but is not limited to, the following kinds of
+contributions:
+
+- Code, usually in the form of a pull request
+- Issues or security vulnerabilities
+- Comments and feedback on pull requests
+
+## Extractive Contributions
+
+The reason for our "human-in-the-loop" contribution policy is that processing
+patches, PRs, RFCs, and comments is not free -- it takes a lot of
+maintainer time and energy to review those contributions! Sending the
+unreviewed output of an LLM to open source project maintainers *extracts* work
+from them in the form of design and code review, so we call this kind of
+contribution an "extractive contribution".
+
+## Transparency
+
+For contributions involving significant AI assistance, we encourage you to disclose
+its use and explain your process. If a submission appears to rely heavily on AI
+without disclosure, we may doubt that the **human-in-the-loop** requirement has
+been met. Please show awareness of your use of AI.
+
+## Copyright
+
+Artificial intelligence systems raise many questions around copyright that have
+yet to be answered. Our policy on AI tools is similar to our copyright policy:
+Contributors are responsible for ensuring that they have the right to
+contribute code under the terms of our license, typically meaning that either
+they, their employer, or their collaborators hold the copyright. Using AI tools
+to regenerate copyrighted material does not remove the copyright, and
+contributors are responsible for ensuring that such material does not appear in
+their contributions. Contributions found to violate this policy will be removed
+just like any other offending contribution.
+
+## Reference
+
+- [LLVM AI Tool Use Policy](https://discourse.llvm.org/t/rfc-llvm-ai-tool-policy-human-in-the-loop/89159)

CMakeLists.txt

@@ -1,9 +1,18 @@
 cmake_minimum_required(VERSION 3.14)
 
+# Build performance optimizations
+set(CMAKE_EXPORT_COMPILE_COMMANDS ON CACHE BOOL "Export compile commands for faster IDE integration")
+set_property(GLOBAL PROPERTY USE_FOLDERS ON)
+
+# Enable parallel compilation on MSVC
+if(MSVC)
+  add_compile_options(/MP)
+endif()
+
 project(
     simdjson
     # The version number is modified by tools/release.py
-    VERSION 4.0.7
+    VERSION 4.4.2
     DESCRIPTION "Parsing gigabytes of JSON per second"
     HOMEPAGE_URL "https://simdjson.org/"
     LANGUAGES CXX C
@@ -20,8 +29,8 @@ string(
 # ---- Options, variables ----
 
 # These version numbers are modified by tools/release.py
-set(SIMDJSON_LIB_VERSION "27.0.0" CACHE STRING "simdjson library version")
-set(SIMDJSON_LIB_SOVERSION "27" CACHE STRING "simdjson library soversion")
+set(SIMDJSON_LIB_VERSION "31.0.0" CACHE STRING "simdjson library version")
+set(SIMDJSON_LIB_SOVERSION "31" CACHE STRING "simdjson library soversion")
 
 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)
@@ -83,10 +92,36 @@ add_library(simdjson ${SIMDJSON_SOURCES})
 add_library(simdjson::simdjson ALIAS simdjson)
 set(SIMDJSON_LIBRARIES simdjson)
 
+# Enable precompiled headers for faster builds
+if(CMAKE_VERSION VERSION_GREATER_EQUAL "3.16")
+  target_precompile_headers(simdjson PRIVATE
+    <algorithm>
+    <array>
+    <atomic>
+    <bit>
+    <cassert>
+    <cctype>
+    <cerrno>
+    <cstddef>
+    <cstdint>
+    <cstdlib>
+    <cstring>
+    <memory>
+    <string>
+    <utility>
+    <vector>
+  )
+endif()
+
 if(SIMDJSON_BUILD_STATIC_LIB)
   add_library(simdjson_static STATIC ${SIMDJSON_SOURCES})
   add_library(simdjson::simdjson_static ALIAS simdjson_static)
   list(APPEND SIMDJSON_LIBRARIES simdjson_static)
+
+  # Reuse precompiled headers for static library
+  if(CMAKE_VERSION VERSION_GREATER_EQUAL "3.16")
+    target_precompile_headers(simdjson_static REUSE_FROM simdjson)
+  endif()
 endif()
 
 set_target_properties(
@@ -112,6 +147,14 @@ simdjson_add_props(
     PRIVATE "$<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}/src>"
 )
 
+# Optimize linker settings for faster builds
+if(MSVC)
+  target_link_options(simdjson PRIVATE /INCREMENTAL)
+  if(CMAKE_BUILD_TYPE STREQUAL "Debug")
+    target_link_options(simdjson PRIVATE /DEBUG:FASTLINK)
+  endif()
+endif()
+
 if(SIMDJSON_STATIC_REFLECTION)
   # We would like to require C++26, but no compiler supports that!
   # This is a hack:
@@ -140,24 +183,6 @@ 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)
-    check_cxx_compiler_flag(-mlasx COMPILER_SUPPORTS_LASX)
-    check_cxx_compiler_flag(-mlsx COMPILER_SUPPORTS_LSX)
-    if(COMPILER_SUPPORTS_LASX AND NOT SIMDJSON_PREFER_LSX)
-        simdjson_add_props(
-            target_compile_options PRIVATE
-            -mlasx
-        )
-    elseif(COMPILER_SUPPORTS_LSX)
-        simdjson_add_props(
-            target_compile_options PRIVATE
-            -mlsx
-        )
-    endif()
-endif()
-
 # GCC and Clang have horrendous Debug builds when using SIMD.
 # A common fix is to use '-Og' instead.
 # bug https://gcc.gnu.org/bugzilla/show_bug.cgi?id=54412
@@ -171,7 +196,12 @@ if(
       target_compile_options PRIVATE
       $<$<CONFIG:DEBUG>:-Og>
   )
-endif()
+  # We still want to enable development checks in Debug mode
+  simdjson_add_props(
+      target_compile_definitions PUBLIC
+      SIMDJSON_DEVELOPMENT_CHECKS
+  )
+  endif()
 
 if(SIMDJSON_ENABLE_THREADS)
   find_package(Threads REQUIRED)

CONTRIBUTING.md

@@ -101,3 +101,10 @@ Getting Started Hacking
 
 An overview of simdjson's directory structure, with pointers to architecture and design
 considerations and other helpful notes, can be found at [HACKING.md](HACKING.md).
+
+
+
+AI Usage Policy
+---------------
+
+Please also review our [AI Usage Policy](AI_USAGE_POLICY.md).

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         = "4.0.7"
+PROJECT_NUMBER         = "4.4.2"
 
 # 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

@@ -110,6 +110,24 @@ workflows used by simdjson.
 Directory Structure and Source
 ------------------------------
 
+Before diving into the directory structure, here are key concepts used in the codebase:
+
+- **Amalgamated File**: A file that is conditionally included in the amalgamation process. These are wrapped in `#ifndef SIMDJSON_CONDITIONAL_INCLUDE` blocks and are included based on the target implementation (e.g., ARM64, x86). They include implementation-specific files (e.g., `arm64.h`) and generic files (e.g., under `generic/`). Amalgamated files have associated dependency files (`dependencies.h`) to track includes.
+
+- **Amalgamator File**: A file that orchestrates the inclusion of amalgamated files. Examples: `arm64.h`, `arm64/implementation.h`, `generic/amalgamated.h`. These are not themselves amalgamated but control conditional inclusions.
+
+- **Free Dependency File**: A top-level header that is always included unconditionally. These do not have dependency files and represent the public API (e.g., main headers).
+
+- **Implementation-Specific File**: A file tied to a specific CPU architecture or instruction set (e.g., `arm64/`, `haswell/`). These must be amalgamated.
+
+- **Generic File**: A shared file (under `generic/` or `simdjson/generic/`) that contains common code included once per implementation.
+
+- **Builtin File**: Special files under `simdjson/builtin/` that handle the builtin implementation, a fallback/default implementation used when no optimized implementation is available.
+
+- **Conditional Include Block**: A section wrapped in `#ifndef SIMDJSON_CONDITIONAL_INCLUDE` for editor-only or implementation-specific content.
+
+The script `singleheader/amalgation_helper.py` will generate an HTML report which you can use to visualize the status of each file.
+
 simdjson's source structure, from the top level, looks like this:
 
 * **CMakeLists.txt:** The main build system.
@@ -133,6 +151,12 @@ simdjson's source structure, from the top level, looks like this:
     * 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.
+  * simdjson/builder.h: the `simdjson::builder` namespace. Includes all public builder classes.
+    * simdjson/builtin/builder.h: the `simdjson::builtin::builder` namespace.
+    * simdjson/arm64|fallback|haswell|icelake|ppc64|westmere/builder.h: the `simdjson::<implementation>::builder` namespace. Builder compiled for the specific implementation.
+    * simdjson/generic/builder/*.h: individual Builder classes, generically written.
+      * simdjson/generic/builder/dependencies.h: dependencies on common, non-implementation-specific simdjson classes. This will be included before including amalgamated.h.
+      * simdjson/generic/builder/amalgamated.h: all generic builder classes for an implementation.
 * **src:** The source files for non-inlined functionality (e.g. the architecture-specific parser
   implementations).
   * simdjson.cpp: A "main source" that includes all implementation files from src/. This is
@@ -147,6 +171,7 @@ Other important files and directories:
 * **.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). If you add a new implementation (e.g., rvv), you need to edit this file (IMPLEMENTATIONS).
+* **singleheader/amalgation_helper.py:** Generates and `amalgamation_report.html` that helps you understand the status of each file.
 * **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:

README.md

@@ -6,7 +6,8 @@
 simdjson : Parsing gigabytes of JSON per second
 ===============================================
 
-<img src="images/logo.png" width="10%" style="float: right">
+<img src="images/official_logo/logo_noir/SVG/logo_simdjson_noir.svg" width="40%" style="float: right">
+
 JSON is everywhere on the Internet. Servers spend a *lot* of time parsing it. We need a fresh
 approach. The simdjson library uses commonly available SIMD instructions and microparallel algorithms
 to parse JSON 4x  faster than RapidJSON and 25x faster than JSON for Modern C++.
@@ -63,10 +64,14 @@ Real-world usage
 - [RonDB](https://github.com/logicalclocks/rondb)
 - [GreptimeDB](https://github.com/GreptimeTeam/greptimedb)
 - [mamba](https://github.com/mamba-org/mamba)
+- [Ladybird Browser](https://ladybird.org)
 
 
 If you are planning to use simdjson in a product, please work from one of our releases.
 
+
+
+
 Quick Start
 -----------
 
@@ -83,7 +88,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;
@@ -113,6 +118,8 @@ Usage documentation is available:
 * [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
 -------------
@@ -181,6 +188,7 @@ We distinguish between "bindings" (which just wrap the C++ code) and a port to a
 - [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.
 - [simdjson-java](https://github.com/simdjson/simdjson-java): Java port.
+- [mruby-fast-json](https://github.com/Asmod4n/mruby-fast-json): mruby binding with high API coverage.
 
 About simdjson
 --------------
@@ -207,6 +215,21 @@ For the video inclined, <br />
 [![simdjson at QCon San Francisco 2019](http://img.youtube.com/vi/wlvKAT7SZIQ/0.jpg)](http://www.youtube.com/watch?v=wlvKAT7SZIQ)<br />
 (It was the best voted talk, we're kinda proud of it.)
 
+Citing this work
+-----------------
+
+If you use simdjson in published research, please cite the software library. A suitable BibTeX entry is:
+
+```bibtex
+@misc{simdjson,
+  title={{The simdjson library: Parsing Gigabytes of JSON per Second}},
+  author={Daniel Lemire and Geoff Langdale and John Keiser and Paul Dreik and Francisco Thiesen and others},
+  year={2019},
+  howpublished={Software library},
+  note={https://github.com/simdjson/simdjson}
+}
+```
+
 Funding
 -------
 
@@ -227,6 +250,13 @@ 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
 -------
 

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/apple/apple_arm_events.h

@@ -245,7 +245,7 @@ static u32 (*kpc_get_counter_count)(u32 classes);
 
 /// Get counter accumulations.
 /// If `all_cpus` is true, the buffer count should not smaller than
-/// (cpu_count * counter_count). Otherwize, the buffer count should not smaller
+/// (cpu_count * counter_count). Otherwise, the buffer count should not smaller
 /// than (counter_count).
 /// @see kpc_get_counter_count(), kpc_cpu_count().
 /// @param all_cpus true for all CPUs, false for current cpu.
@@ -374,7 +374,7 @@ static int kperf_lightweight_pet_set(u32 enabled) {
 // These functions do not require root privileges.
 // -----------------------------------------------------------------------------
 
-// KPEP CPU archtecture constants.
+// KPEP CPU architecture constants.
 #define KPEP_ARCH_I386 0
 #define KPEP_ARCH_X86_64 1
 #define KPEP_ARCH_ARM 2
@@ -414,7 +414,7 @@ typedef struct kpep_db {
   usize fixed_counter_count;
   usize config_counter_count;
   usize power_counter_count;
-  u32 archtecture; ///< see `KPEP CPU archtecture constants` above.
+  u32 architecture; ///< see `KPEP CPU architecture constants` above.
   u32 fixed_counter_bits;
   u32 config_counter_bits;
   u32 power_counter_bits;

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/static_reflect/CMakeLists.txt

@@ -8,7 +8,7 @@ CPMAddPackage(
 
 option(SIMDJSON_USE_RUST "Build the static_reflect benchmark" OFF)
 
-if(SIMDJSON_USER_RUST)
+if(SIMDJSON_USE_RUST)
   if(NOT WIN32)
   # We want the check whether Rust is available before trying to build a crate.
   CPMAddPackage(
@@ -39,9 +39,9 @@ if(SIMDJSON_USER_RUST)
       message(STATUS "curl https://sh.rustup.rs -sSf | sh")
     endif()
   endif()
-else(SIMDJSON_USER_RUST)
+else(SIMDJSON_USE_RUST)
   message(STATUS "We will not benchmark serde-benchmark." )
-endif(SIMDJSON_USER_RUST)
+endif(SIMDJSON_USE_RUST)
 
 # Add the benchmark executable targets
 add_subdirectory(twitter_benchmark)

benchmark/static_reflect/citm_catalog_benchmark/CMakeLists.txt

@@ -1,4 +1,5 @@
 add_executable(benchmark_serialization_citm_catalog benchmark_serialization_citm_catalog.cpp)
+add_executable(benchmark_parsing_citm benchmark_parsing_citm.cpp)
 
 # Link with Rust benchmarking code if available
 if(TARGET serde-benchmark)
@@ -11,4 +12,29 @@ target_link_libraries(benchmark_serialization_citm_catalog PRIVATE simdjson::sim
 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}")
+if(TARGET yyjson)
+    target_link_libraries(benchmark_serialization_citm_catalog PRIVATE yyjson)
+    target_compile_definitions(benchmark_serialization_citm_catalog PRIVATE SIMDJSON_COMPETITION_YYJSON)
+endif()
+
+target_compile_definitions(benchmark_serialization_citm_catalog PRIVATE JSON_FILE="${BENCH_CITM_JSON}")
+
+# Configuration for parsing benchmark
+if(TARGET serde-benchmark)
+    target_link_libraries(benchmark_parsing_citm PRIVATE serde-benchmark)
+    target_compile_definitions(benchmark_parsing_citm PRIVATE SIMDJSON_RUST_VERSION="${Rust_VERSION}")
+endif()
+
+target_link_libraries(benchmark_parsing_citm PRIVATE simdjson::simdjson nlohmann_json)
+
+if(TARGET rapidjson)
+    target_link_libraries(benchmark_parsing_citm PRIVATE rapidjson)
+    target_compile_definitions(benchmark_parsing_citm PRIVATE SIMDJSON_COMPETITION_RAPIDJSON)
+endif()
+
+if(TARGET yyjson)
+    target_link_libraries(benchmark_parsing_citm PRIVATE yyjson)
+    target_compile_definitions(benchmark_parsing_citm PRIVATE SIMDJSON_COMPETITION_YYJSON)
+endif()
+
+target_compile_definitions(benchmark_parsing_citm PRIVATE JSON_FILE="${BENCH_CITM_JSON}")

benchmark/static_reflect/citm_catalog_benchmark/benchmark_parsing_citm.cpp

@@ -0,0 +1,563 @@
+#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"
+
+#ifdef SIMDJSON_COMPETITION_RAPIDJSON
+#include "rapidjson_citm_catalog_data.h"
+#endif
+
+#ifdef SIMDJSON_COMPETITION_YYJSON
+#include "yyjson_citm_catalog_data.h"
+#endif
+
+#ifdef SIMDJSON_RUST_VERSION
+#include "../serde-benchmark/serde_benchmark.h"
+
+void bench_rust_parsing(const std::string &json_str) {
+  size_t input_volume = json_str.size();
+  printf("# input volume: %zu bytes\n", input_volume);
+
+  volatile bool result = true;
+  pretty_print(1, input_volume, "bench_rust_parsing",
+               bench([&json_str, &result]() {
+                 serde_benchmark::CitmCatalog *catalog = serde_benchmark::citm_from_str(json_str.c_str(), json_str.size());
+                 result = (catalog != nullptr);
+                 if (catalog) {
+                   serde_benchmark::free_citm(catalog);
+                 }
+                 if (!result) {
+                   printf("parse error\n");
+                 }
+               }));
+}
+#endif
+
+template <class T> void bench_simdjson_static_reflection_parsing(const std::string &json_str) {
+  size_t input_volume = json_str.size();
+  printf("# input volume: %zu bytes\n", input_volume);
+
+  // Pre-allocate padded buffer outside the benchmark loop
+  std::string mutable_json = json_str;
+  simdjson::pad(mutable_json);
+
+  volatile bool result = true;
+  pretty_print(1, input_volume, "bench_simdjson_static_reflection_parsing",
+               bench([&mutable_json, &result]() {
+                 simdjson::ondemand::parser parser;
+                 simdjson::ondemand::document doc;
+                 if(parser.iterate(mutable_json).get(doc)) {
+                   result = false;
+                   return;
+                 }
+                 T my_struct;
+                 if(doc.get<T>().get(my_struct)) {
+                   result = false;
+                 }
+                 if (!result) {
+                   printf("parse error\n");
+                 }
+               }));
+}
+
+#if SIMDJSON_STATIC_REFLECTION
+template <class T> void bench_simdjson_from_parsing(const std::string &json_str) {
+  size_t input_volume = json_str.size();
+  printf("# input volume: %zu bytes\n", input_volume);
+
+  // Pre-allocate padded buffer outside the benchmark loop
+  simdjson::padded_string padded = simdjson::padded_string(json_str);
+
+  volatile bool result = true;
+  pretty_print(1, input_volume, "bench_simdjson_from_parsing",
+               bench([&padded, &result]() {
+                 T my_struct;
+                 auto err = simdjson::from(padded).get(my_struct);
+                  if (err) {
+                    result = false;
+                    printf("parse error: %s\n", simdjson::error_message(err));
+                    return;
+                  }
+               }));
+}
+#endif
+
+// nlohmann::json deserialization functions
+void from_json(const nlohmann::json &j, CITMPrice &p) {
+    j.at("amount").get_to(p.amount);
+    j.at("audienceSubCategoryId").get_to(p.audienceSubCategoryId);
+    j.at("seatCategoryId").get_to(p.seatCategoryId);
+}
+
+void from_json(const nlohmann::json &j, CITMArea &a) {
+    j.at("areaId").get_to(a.areaId);
+    j.at("blockIds").get_to(a.blockIds);
+}
+
+void from_json(const nlohmann::json &j, CITMSeatCategory &s) {
+    j.at("areas").get_to(s.areas);
+    j.at("seatCategoryId").get_to(s.seatCategoryId);
+}
+
+void from_json(const nlohmann::json &j, CITMPerformance &p) {
+    j.at("id").get_to(p.id);
+    j.at("eventId").get_to(p.eventId);
+    if (j.contains("logo") && !j["logo"].is_null()) {
+        p.logo = j["logo"].get<std::string>();
+    }
+    if (j.contains("name") && !j["name"].is_null()) {
+        p.name = j["name"].get<std::string>();
+    }
+    j.at("prices").get_to(p.prices);
+    j.at("seatCategories").get_to(p.seatCategories);
+    if (j.contains("seatMapImage") && !j["seatMapImage"].is_null()) {
+        p.seatMapImage = j["seatMapImage"].get<std::string>();
+    }
+    j.at("start").get_to(p.start);
+    j.at("venueCode").get_to(p.venueCode);
+}
+
+void from_json(const nlohmann::json &j, CITMEvent &e) {
+    j.at("id").get_to(e.id);
+    j.at("name").get_to(e.name);
+    if (j.contains("description") && !j["description"].is_null()) {
+        e.description = j["description"].get<std::string>();
+    }
+    if (j.contains("logo") && !j["logo"].is_null()) {
+        e.logo = j["logo"].get<std::string>();
+    }
+    j.at("subTopicIds").get_to(e.subTopicIds);
+    if (j.contains("subjectCode") && !j["subjectCode"].is_null()) {
+        e.subjectCode = j["subjectCode"].get<std::string>();
+    }
+    if (j.contains("subtitle") && !j["subtitle"].is_null()) {
+        e.subtitle = j["subtitle"].get<std::string>();
+    }
+    j.at("topicIds").get_to(e.topicIds);
+}
+
+void from_json(const nlohmann::json &j, CitmCatalog &c) {
+    j.at("events").get_to(c.events);
+    j.at("performances").get_to(c.performances);
+}
+
+CitmCatalog nlohmann_deserialize(const std::string &json_str) {
+    nlohmann::json j = nlohmann::json::parse(json_str);
+    return j.get<CitmCatalog>();
+}
+
+void bench_nlohmann_parsing(const std::string &json_str) {
+  size_t input_volume = json_str.size();
+  printf("# input volume: %zu bytes\n", input_volume);
+
+  volatile bool result = true;
+  pretty_print(1, input_volume, "bench_nlohmann_parsing",
+               bench([&json_str, &result]() {
+                 try {
+                   CitmCatalog data = nlohmann_deserialize(json_str);
+                   result = true;
+                 } catch (...) {
+                   result = false;
+                   printf("parse error\n");
+                 }
+               }));
+}
+
+#ifdef SIMDJSON_COMPETITION_RAPIDJSON
+CitmCatalog rapidjson_deserialize(const std::string &json_str) {
+    rapidjson::Document doc;
+    doc.Parse(json_str.c_str());
+
+    if (doc.HasParseError()) {
+        throw std::runtime_error("RapidJSON parse error");
+    }
+
+    CitmCatalog catalog;
+
+    // Parse events
+    if (doc.HasMember("events") && doc["events"].IsObject()) {
+        for (auto& m : doc["events"].GetObject()) {
+            CITMEvent event;
+            const auto& e = m.value;
+
+            event.id = e["id"].GetUint64();
+            event.name = e["name"].GetString();
+            if (e.HasMember("description") && !e["description"].IsNull()) {
+                event.description = e["description"].GetString();
+            }
+            if (e.HasMember("logo") && !e["logo"].IsNull()) {
+                event.logo = e["logo"].GetString();
+            }
+
+            event.subTopicIds.clear();
+            for (auto& id : e["subTopicIds"].GetArray()) {
+                event.subTopicIds.push_back(id.GetUint64());
+            }
+
+            if (e.HasMember("subjectCode") && !e["subjectCode"].IsNull()) {
+                event.subjectCode = e["subjectCode"].GetString();
+            }
+            if (e.HasMember("subtitle") && !e["subtitle"].IsNull()) {
+                event.subtitle = e["subtitle"].GetString();
+            }
+
+            event.topicIds.clear();
+            for (auto& id : e["topicIds"].GetArray()) {
+                event.topicIds.push_back(id.GetUint64());
+            }
+
+            catalog.events[m.name.GetString()] = event;
+        }
+    }
+
+    // Parse performances
+    if (doc.HasMember("performances") && doc["performances"].IsArray()) {
+        for (auto& p : doc["performances"].GetArray()) {
+            CITMPerformance perf;
+
+            perf.id = p["id"].GetUint64();
+            perf.eventId = p["eventId"].GetUint64();
+            if (p.HasMember("logo") && !p["logo"].IsNull()) {
+                perf.logo = p["logo"].GetString();
+            }
+            if (p.HasMember("name") && !p["name"].IsNull()) {
+                perf.name = p["name"].GetString();
+            }
+
+            // Parse prices
+            for (auto& price : p["prices"].GetArray()) {
+                CITMPrice pr;
+                pr.amount = price["amount"].GetUint64();
+                pr.audienceSubCategoryId = price["audienceSubCategoryId"].GetUint64();
+                pr.seatCategoryId = price["seatCategoryId"].GetUint64();
+                perf.prices.push_back(pr);
+            }
+
+            // Parse seat categories
+            for (auto& sc : p["seatCategories"].GetArray()) {
+                CITMSeatCategory seatCat;
+                seatCat.seatCategoryId = sc["seatCategoryId"].GetUint64();
+
+                for (auto& area : sc["areas"].GetArray()) {
+                    CITMArea ar;
+                    ar.areaId = area["areaId"].GetUint64();
+                    for (auto& block : area["blockIds"].GetArray()) {
+                        ar.blockIds.push_back(block.GetUint64());
+                    }
+                    seatCat.areas.push_back(ar);
+                }
+                perf.seatCategories.push_back(seatCat);
+            }
+
+            if (p.HasMember("seatMapImage") && !p["seatMapImage"].IsNull()) {
+                perf.seatMapImage = p["seatMapImage"].GetString();
+            }
+            perf.start = p["start"].GetUint64();
+            perf.venueCode = p["venueCode"].GetString();
+
+            catalog.performances.push_back(perf);
+        }
+    }
+
+    return catalog;
+}
+
+void bench_rapidjson_parsing(const std::string &json_str) {
+  size_t input_volume = json_str.size();
+  printf("# input volume: %zu bytes\n", input_volume);
+
+  volatile bool result = true;
+  pretty_print(1, input_volume, "bench_rapidjson_parsing",
+               bench([&json_str, &result]() {
+                 try {
+                   CitmCatalog data = rapidjson_deserialize(json_str);
+                   result = true;
+                 } catch (...) {
+                   result = false;
+                   printf("parse error\n");
+                 }
+               }));
+}
+#endif
+
+#ifdef SIMDJSON_COMPETITION_YYJSON
+CitmCatalog yyjson_deserialize(const std::string &json_str) {
+    yyjson_doc *doc = yyjson_read(json_str.c_str(), json_str.size(), 0);
+    if (!doc) {
+        throw std::runtime_error("YYJson parse error");
+    }
+
+    yyjson_val *root = yyjson_doc_get_root(doc);
+    CitmCatalog catalog;
+
+    // Parse events
+    yyjson_val *events = yyjson_obj_get(root, "events");
+    if (events) {
+        size_t idx, max;
+        yyjson_val *key, *val;
+        yyjson_obj_foreach(events, idx, max, key, val) {
+            CITMEvent event;
+
+            event.id = yyjson_get_uint(yyjson_obj_get(val, "id"));
+            const char* name = yyjson_get_str(yyjson_obj_get(val, "name"));
+            if (name) event.name = name;
+
+            yyjson_val *desc = yyjson_obj_get(val, "description");
+            if (desc && !yyjson_is_null(desc)) {
+                const char* str = yyjson_get_str(desc);
+                if (str) event.description = str;
+            }
+
+            yyjson_val *logo = yyjson_obj_get(val, "logo");
+            if (logo && !yyjson_is_null(logo)) {
+                const char* str = yyjson_get_str(logo);
+                if (str) event.logo = str;
+            }
+
+            yyjson_val *subTopics = yyjson_obj_get(val, "subTopicIds");
+            if (subTopics) {
+                size_t sidx, smax;
+                yyjson_val *sval;
+                yyjson_arr_foreach(subTopics, sidx, smax, sval) {
+                    event.subTopicIds.push_back(yyjson_get_uint(sval));
+                }
+            }
+
+            yyjson_val *subjectCode = yyjson_obj_get(val, "subjectCode");
+            if (subjectCode && !yyjson_is_null(subjectCode)) {
+                const char* str = yyjson_get_str(subjectCode);
+                if (str) event.subjectCode = str;
+            }
+
+            yyjson_val *subtitle = yyjson_obj_get(val, "subtitle");
+            if (subtitle && !yyjson_is_null(subtitle)) {
+                const char* str = yyjson_get_str(subtitle);
+                if (str) event.subtitle = str;
+            }
+
+            yyjson_val *topics = yyjson_obj_get(val, "topicIds");
+            if (topics) {
+                size_t tidx, tmax;
+                yyjson_val *tval;
+                yyjson_arr_foreach(topics, tidx, tmax, tval) {
+                    event.topicIds.push_back(yyjson_get_uint(tval));
+                }
+            }
+
+            const char* keyStr = yyjson_get_str(key);
+            if (keyStr) {
+                catalog.events[keyStr] = event;
+            }
+        }
+    }
+
+    // Parse performances
+    yyjson_val *performances = yyjson_obj_get(root, "performances");
+    if (performances) {
+        size_t idx, max;
+        yyjson_val *val;
+        yyjson_arr_foreach(performances, idx, max, val) {
+            CITMPerformance perf;
+
+            perf.id = yyjson_get_uint(yyjson_obj_get(val, "id"));
+            perf.eventId = yyjson_get_uint(yyjson_obj_get(val, "eventId"));
+
+            yyjson_val *logo = yyjson_obj_get(val, "logo");
+            if (logo && !yyjson_is_null(logo)) {
+                const char* str = yyjson_get_str(logo);
+                if (str) perf.logo = str;
+            }
+
+            yyjson_val *name = yyjson_obj_get(val, "name");
+            if (name && !yyjson_is_null(name)) {
+                const char* str = yyjson_get_str(name);
+                if (str) perf.name = str;
+            }
+
+            // Parse prices
+            yyjson_val *prices = yyjson_obj_get(val, "prices");
+            if (prices) {
+                size_t pidx, pmax;
+                yyjson_val *pval;
+                yyjson_arr_foreach(prices, pidx, pmax, pval) {
+                    CITMPrice price;
+                    price.amount = yyjson_get_uint(yyjson_obj_get(pval, "amount"));
+                    price.audienceSubCategoryId = yyjson_get_uint(yyjson_obj_get(pval, "audienceSubCategoryId"));
+                    price.seatCategoryId = yyjson_get_uint(yyjson_obj_get(pval, "seatCategoryId"));
+                    perf.prices.push_back(price);
+                }
+            }
+
+            // Parse seat categories
+            yyjson_val *seatCats = yyjson_obj_get(val, "seatCategories");
+            if (seatCats) {
+                size_t scidx, scmax;
+                yyjson_val *scval;
+                yyjson_arr_foreach(seatCats, scidx, scmax, scval) {
+                    CITMSeatCategory seatCat;
+                    seatCat.seatCategoryId = yyjson_get_uint(yyjson_obj_get(scval, "seatCategoryId"));
+
+                    yyjson_val *areas = yyjson_obj_get(scval, "areas");
+                    if (areas) {
+                        size_t aidx, amax;
+                        yyjson_val *aval;
+                        yyjson_arr_foreach(areas, aidx, amax, aval) {
+                            CITMArea area;
+                            area.areaId = yyjson_get_uint(yyjson_obj_get(aval, "areaId"));
+
+                            yyjson_val *blocks = yyjson_obj_get(aval, "blockIds");
+                            if (blocks) {
+                                size_t bidx, bmax;
+                                yyjson_val *bval;
+                                yyjson_arr_foreach(blocks, bidx, bmax, bval) {
+                                    area.blockIds.push_back(yyjson_get_uint(bval));
+                                }
+                            }
+                            seatCat.areas.push_back(area);
+                        }
+                    }
+                    perf.seatCategories.push_back(seatCat);
+                }
+            }
+
+            yyjson_val *seatMapImage = yyjson_obj_get(val, "seatMapImage");
+            if (seatMapImage && !yyjson_is_null(seatMapImage)) {
+                const char* str = yyjson_get_str(seatMapImage);
+                if (str) perf.seatMapImage = str;
+            }
+
+            perf.start = yyjson_get_uint(yyjson_obj_get(val, "start"));
+            const char* venueCode = yyjson_get_str(yyjson_obj_get(val, "venueCode"));
+            if (venueCode) perf.venueCode = venueCode;
+
+            catalog.performances.push_back(perf);
+        }
+    }
+
+    yyjson_doc_free(doc);
+    return catalog;
+}
+
+void bench_yyjson_parsing(const std::string &json_str) {
+  size_t input_volume = json_str.size();
+  printf("# input volume: %zu bytes\n", input_volume);
+
+  volatile bool result = true;
+  pretty_print(1, input_volume, "bench_yyjson_parsing",
+               bench([&json_str, &result]() {
+                 try {
+                   CitmCatalog data = yyjson_deserialize(json_str);
+                   result = true;
+                 } catch (...) {
+                   result = false;
+                   printf("parse error\n");
+                 }
+               }));
+}
+#endif
+
+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);
+  stream.exceptions(std::ios_base::badbit);
+
+  if (!stream) {
+    std::cerr << "Error: Failed to open file " << filename << std::endl;
+    exit(EXIT_FAILURE);
+  }
+
+  std::string out;
+  auto buf = std::string(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 matches any of the comma-separated filters
+bool matches_filter(const std::string& benchmark_name, const std::string& filter) {
+  if (filter.empty()) return true;
+
+  // Split filter by comma
+  size_t start = 0;
+  size_t end = filter.find(',');
+  while (end != std::string::npos) {
+    std::string token = filter.substr(start, end - start);
+    if (benchmark_name.find(token) != std::string::npos) {
+      return true;
+    }
+    start = end + 1;
+    end = filter.find(',', start);
+  }
+  // Check last token
+  std::string token = filter.substr(start);
+  return benchmark_name.find(token) != std::string::npos;
+}
+
+int main(int argc, char *argv[]) {
+  // Get the JSON file path from preprocessor or use default
+  std::string filename;
+#ifdef JSON_FILE
+  filename = JSON_FILE;
+#else
+  filename = "jsonexamples/citm_catalog.json";
+#endif
+
+  std::string json_str = read_file(filename);
+
+  // Parse command-line arguments for filter
+  std::string filter;
+  for (int i = 1; i < argc; i++) {
+    std::string arg = argv[i];
+    if (arg == "-f" && i + 1 < argc) {
+      filter = argv[i + 1];
+      printf("# Filter: %s\n", filter.c_str());
+      i++;
+    }
+  }
+
+  // If no filter provided, run all benchmarks
+  if (filter.empty()) {
+    printf("# Running all benchmarks (use -f <filter> to run specific ones)\n");
+  }
+
+  // Benchmarking the parsing
+  if (matches_filter("nlohmann", filter)) {
+    bench_nlohmann_parsing(json_str);
+  }
+#ifdef SIMDJSON_COMPETITION_RAPIDJSON
+  if (matches_filter("rapidjson", filter)) {
+    bench_rapidjson_parsing(json_str);
+  }
+#endif
+#ifdef SIMDJSON_COMPETITION_YYJSON
+  if (matches_filter("yyjson", filter)) {
+    bench_yyjson_parsing(json_str);
+  }
+#endif
+  if (matches_filter("simdjson_static_reflection", filter)) {
+    bench_simdjson_static_reflection_parsing<CitmCatalog>(json_str);
+  }
+#if SIMDJSON_STATIC_REFLECTION
+  if (matches_filter("simdjson_from", filter)) {
+    bench_simdjson_from_parsing<CitmCatalog>(json_str);
+  }
+#endif
+#ifdef SIMDJSON_RUST_VERSION
+  if (matches_filter("rust", filter)) {
+    printf("# Note: Rust/Serde parsing test\n");
+    bench_rust_parsing(json_str);
+  }
+#endif
+  return EXIT_SUCCESS;
+}

benchmark/static_reflect/citm_catalog_benchmark/benchmark_serialization_citm_catalog.cpp

@@ -11,6 +11,10 @@
 #include "nlohmann_citm_catalog_data.h"
 #include "../benchmark_utils/benchmark_helper.h"
 
+#ifdef SIMDJSON_COMPETITION_YYJSON
+#include "yyjson_citm_catalog_data.h"
+#endif
+
 #if SIMDJSON_BENCH_CPP_REFLECT
 #include <rfl.hpp>
 #include <rfl/json.hpp>
@@ -35,20 +39,15 @@ void bench_reflect_cpp(CitmCatalog &data) {
 #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);
+  serde_benchmark::set_citm_data(data);
+  size_t output_volume = serde_benchmark::serialize_citm_to_string();
   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));
+               bench([&measured_volume, &output_volume]() {
+                 measured_volume = serde_benchmark::serialize_citm_to_string();
                }));
-  serde_benchmark::free_str(const_cast<char*>(output));
 }
 #endif // SIMDJSON_RUST_VERSION
 
@@ -68,7 +67,55 @@ void bench_nlohmann(CitmCatalog &data) {
                }));
 }
 
+#ifdef SIMDJSON_COMPETITION_YYJSON
+void bench_yyjson(CitmCatalog &data) {
+  std::string output = yyjson_serialize_citm(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_yyjson",
+               bench([&data, &measured_volume, &output_volume]() {
+                 std::string output = yyjson_serialize_citm(data);
+                 measured_volume = output.size();
+                 if (measured_volume != output_volume) {
+                   printf("mismatch\n");
+                 }
+               }));
+}
+#endif
+
+// Fair allocation variant: allocates fresh buffer each iteration (matches other libraries)
 void bench_simdjson_static_reflection(CitmCatalog &data) {
+  // First run to determine expected size
+  simdjson::builder::string_builder sb_init;
+  simdjson::builder::append(sb_init, data);
+  std::string_view p_init;
+  if(sb_init.view().get(p_init)) {
+    std::cerr << "Error!" << std::endl;
+  }
+  size_t output_volume = p_init.size();
+  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]() {
+                 // Fresh allocation each iteration - fair comparison
+                 simdjson::builder::string_builder sb;
+                 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");
+                 }
+               }));
+}
+
+// Optimized variant: reuses buffer across iterations (shows API potential)
+void bench_simdjson_static_reflection_reuse(CitmCatalog &data) {
   simdjson::builder::string_builder sb;
   simdjson::builder::append(sb, data);
   std::string_view p;
@@ -80,7 +127,7 @@ void bench_simdjson_static_reflection(CitmCatalog &data) {
   printf("# output volume: %zu bytes\n", output_volume);
 
   volatile size_t measured_volume = 0;
-  pretty_print(sizeof(data), output_volume, "bench_simdjson_static_reflection",
+  pretty_print(sizeof(data), output_volume, "bench_simdjson_reuse_buffer",
                bench([&data, &measured_volume, &output_volume, &sb]() {
                  sb.clear();
                  simdjson::builder::append(sb, data);
@@ -95,25 +142,97 @@ void bench_simdjson_static_reflection(CitmCatalog &data) {
                }));
 }
 
-std::string read_file(const std::string &file_path, size_t read_size = 65536) {
+#if SIMDJSON_STATIC_REFLECTION
+// Fair allocation variant: allocates fresh string each iteration
+void bench_simdjson_to(CitmCatalog &data) {
+  // First run to determine size
+  std::string output_init;
+  if (simdjson::error_code err = simdjson::builder::to_json(data, output_init); err) {
+    std::cerr << "Error in to_json initialization!" << simdjson::error_message(err) << std::endl;
+    return;
+  }
+  size_t output_volume = output_init.size();
+  printf("# output volume: %zu bytes\n", output_volume);
+
+  volatile size_t measured_volume = 0;
+  pretty_print(sizeof(data), output_volume, "bench_simdjson_to",
+               bench([&data, &measured_volume, &output_volume]() {
+                 // Fresh allocation each iteration - fair comparison
+                 std::string output;
+                 if (simdjson::error_code err = simdjson::builder::to_json(data, output); err) {
+                   std::cerr << "Error in to_json!" << simdjson::error_message(err) << std::endl;
+                   return;
+                 }
+                 measured_volume = output.size();
+                 if (measured_volume != output_volume) {
+                   printf("mismatch\n");
+                 }
+               }));
+}
+
+// Optimized variant: reuses pre-allocated string
+void bench_simdjson_to_reuse(CitmCatalog &data) {
+  std::string output;
+  if (simdjson::error_code err = simdjson::builder::to_json(data, output); err) {
+    std::cerr << "Error in to_json initialization!" << simdjson::error_message(err) << std::endl;
+    return;
+  }
+  size_t output_volume = output.size();
+  printf("# output volume: %zu bytes\n", output_volume);
+
+  // Pre-allocate string with sufficient capacity to avoid reallocation
+  output.reserve(output_volume * 2);
+
+  volatile size_t measured_volume = 0;
+  pretty_print(sizeof(data), output_volume, "bench_simdjson_to_reuse",
+               bench([&data, &measured_volume, &output_volume, &output]() {
+                 // Reuse the pre-allocated string - avoids allocation
+                 if (simdjson::error_code err = simdjson::builder::to_json(data, output); err) {
+                   std::cerr << "Error in to_json!" << simdjson::error_message(err) << std::endl;
+                   return;
+                 }
+                 measured_volume = output.size();
+                 if (measured_volume != output_volume) {
+                   printf("mismatch\n");
+                 }
+               }));
+}
+#endif
+
+simdjson::padded_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;
+  simdjson::padded_string_builder builder;
   std::string buf(read_size, '\0');
   while (stream.read(&buf[0], read_size)) {
-    out.append(buf, 0, size_t(stream.gcount()));
+    builder.append(buf.data(), size_t(stream.gcount()));
   }
-  out.append(buf, 0, size_t(stream.gcount()));
-  return out;
+  builder.append(buf.data(), size_t(stream.gcount()));
+  return builder.convert();
 }
 
-// Function to check if benchmark name contains filter substring
+// Function to check if benchmark name matches any of the comma-separated filters
 bool matches_filter(const std::string& benchmark_name, const std::string& filter) {
-  return filter.empty() || benchmark_name.find(filter) != std::string::npos;
+  if (filter.empty()) return true;
+
+  // Split filter by comma
+  size_t start = 0;
+  size_t end = filter.find(',');
+  while (end != std::string::npos) {
+    std::string token = filter.substr(start, end - start);
+    if (benchmark_name.find(token) != std::string::npos) {
+      return true;
+    }
+    start = end + 1;
+    end = filter.find(',', start);
+  }
+  // Check last token
+  std::string token = filter.substr(start);
+  return benchmark_name.find(token) != std::string::npos;
 }
 
 int main(int argc, char* argv[]) {
@@ -131,12 +250,12 @@ int main(int argc, char* argv[]) {
       }
   }
   // Testing correctness of round-trip (serialization + deserialization)
-  std::string json_str = read_file(JSON_FILE);
+  simdjson::padded_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)) {
+  if(parser.iterate(json_str).get(doc)) {
     std::cerr << "Error loading the document!" << std::endl;
     return EXIT_FAILURE;
   }
@@ -147,18 +266,37 @@ int main(int argc, char* argv[]) {
   }
 
   // Benchmarking the serialization
+  // Note: simdjson benchmarks include both "fair" (fresh allocation) and "reuse" (buffer reuse) variants
+  // The "fair" variants allocate fresh memory each iteration, matching other libraries' behavior
+  // The "reuse" variants demonstrate the API's potential when buffer reuse is possible
+
   if (matches_filter("nlohmann", filter)) {
     bench_nlohmann(my_struct);
   }
+#ifdef SIMDJSON_COMPETITION_YYJSON
+  if (matches_filter("yyjson", filter)) {
+    bench_yyjson(my_struct);
+  }
+#endif
   if (matches_filter("simdjson_static_reflection", filter)) {
     bench_simdjson_static_reflection(my_struct);
   }
+  if (matches_filter("simdjson_reuse", filter)) {
+    bench_simdjson_static_reflection_reuse(my_struct);
+  }
+#if SIMDJSON_STATIC_REFLECTION
+  if (matches_filter("simdjson_to", filter)) {
+    bench_simdjson_to(my_struct);
+  }
+  if (matches_filter("simdjson_to_reuse", filter)) {
+    bench_simdjson_to_reuse(my_struct);
+  }
+#endif
 #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());
+      serde_benchmark::citm_from_str(json_str.data(), json_str.size());
 
     if (rust_data == nullptr) {
       printf("# Failed to initialize Rust data structure\n");

benchmark/static_reflect/citm_catalog_benchmark/citm_catalog_data.h

@@ -4,79 +4,65 @@
 #include <string>
 #include <vector>
 #include <map>
+#include <optional>
+#include <cstdint>
 
-struct Area {
-  int64_t id;
-  std::string name;
-  int64_t parent;
-  std::vector<int64_t> childAreas;
-  bool operator==(const Area &other) const = default;
+// Price structure - field names must match JSON keys for reflection
+struct CITMPrice {
+    uint64_t amount;
+    uint64_t audienceSubCategoryId;
+    uint64_t seatCategoryId;
+    bool operator==(const CITMPrice&) const = default;
 };
 
-struct AudienceSubCategory {
-  int64_t id;
-  std::string name;
-  int64_t parent;
-  bool operator==(const AudienceSubCategory &other) const = default;
+struct CITMArea {
+    uint64_t areaId;
+    std::vector<uint64_t> blockIds;
+    bool operator==(const CITMArea&) 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 CITMSeatCategory {
+    std::vector<CITMArea> areas;
+    uint64_t seatCategoryId;
+    bool operator==(const CITMSeatCategory&) 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 CITMPerformance {
+    uint64_t id;
+    uint64_t eventId;
+    std::optional<std::string> logo;
+    std::optional<std::string> name;
+    std::vector<CITMPrice> prices;
+    std::vector<CITMSeatCategory> seatCategories;
+    std::optional<std::string> seatMapImage;
+    uint64_t start;
+    std::string venueCode;
+    bool operator==(const CITMPerformance&) 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 CITMEvent {
+    uint64_t id;
+    std::string name;
+    std::optional<std::string> description;
+    std::optional<std::string> logo;
+    std::vector<uint64_t> subTopicIds;
+    std::optional<std::string> subjectCode;
+    std::optional<std::string> subtitle;
+    std::vector<uint64_t> topicIds;
+    bool operator==(const CITMEvent&) 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;
+    std::map<std::string, CITMEvent> events;
+    std::vector<CITMPerformance> performances;
+    bool operator==(const CitmCatalog&) const = default;
 };
 
-#endif
+// Type aliases
+using Event = CITMEvent;
+using Performance = CITMPerformance;
+using Price = CITMPrice;
+using SeatArea = CITMArea;
+using SeatCategoryInfo = CITMSeatCategory;
+
+#endif

benchmark/static_reflect/citm_catalog_benchmark/nlohmann_citm_catalog_data.h

@@ -8,164 +8,72 @@
 
 using json = nlohmann::json;
 
-// ---- Area ----
-inline void to_json(json &j, const Area &a) {
+// ---- CITMPrice ----
+inline void to_json(json &j, const CITMPrice &p) {
     j = json{
-      {"id", a.id},
-      {"name", a.name},
-      {"parent", a.parent},
-      {"childAreas", a.childAreas}
+      {"amount", p.amount},
+      {"audienceSubCategoryId", p.audienceSubCategoryId},
+      {"seatCategoryId", p.seatCategoryId}
     };
 }
-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) {
+// ---- CITMArea ----
+inline void to_json(json &j, const CITMArea &a) {
     j = json{
-      {"id", asc.id},
-      {"name", asc.name},
-      {"parent", asc.parent}
+      {"areaId", a.areaId},
+      {"blockIds", a.blockIds}
     };
 }
-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) {
+// ---- CITMSeatCategory ----
+inline void to_json(json &j, const CITMSeatCategory &s) {
     j = json{
-      {"id", e.id},
-      {"name", e.name},
-      {"description", e.description},
-      {"subTopic", e.subTopic},
-      {"topic", e.topic},
-      {"audience", e.audience}
+      {"areas", s.areas},
+      {"seatCategoryId", s.seatCategoryId}
     };
 }
-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) {
+// ---- CITMPerformance ----
+inline void to_json(json &j, const CITMPerformance &p) {
     j = json{
       {"id", p.id},
+      {"eventId", p.eventId},
+      {"logo", p.logo},
       {"name", p.name},
-      {"event", p.event},
+      {"prices", p.prices},
+      {"seatCategories", p.seatCategories},
+      {"seatMapImage", p.seatMapImage},
       {"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) {
+// ---- CITMEvent ----
+inline void to_json(json &j, const CITMEvent &e) {
     j = json{
-      {"id", sc.id},
-      {"name", sc.name},
-      {"areas", sc.areas}
+      {"id", e.id},
+      {"name", e.name},
+      {"description", e.description},
+      {"logo", e.logo},
+      {"subTopicIds", e.subTopicIds},
+      {"subjectCode", e.subjectCode},
+      {"subtitle", e.subtitle},
+      {"topicIds", e.topicIds}
     };
 }
-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}
+      {"performances", c.performances}
     };
 }
-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
+// Serialization function
 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/citm_catalog_benchmark/rapidjson_citm_catalog_data.h

@@ -0,0 +1,189 @@
+#ifndef RAPIDJSON_CITM_CATALOG_DATA_H
+#define RAPIDJSON_CITM_CATALOG_DATA_H
+
+#include "citm_catalog_data.h"
+#include <rapidjson/document.h>
+#include <rapidjson/writer.h>
+#include <rapidjson/stringbuffer.h>
+#include <rapidjson/error/en.h>
+
+using namespace rapidjson;
+
+// RapidJSON deserialization for CITM Catalog data
+CitmCatalog rapidjson_deserialize_citm(const std::string& json_str) {
+    Document doc;
+    doc.Parse(json_str.c_str());
+
+    if (doc.HasParseError()) {
+        throw std::runtime_error("RapidJSON parse error");
+    }
+
+    CitmCatalog catalog;
+
+    // Parse events
+    if (doc.HasMember("events") && doc["events"].IsObject()) {
+        const Value& events = doc["events"];
+        for (auto it = events.MemberBegin(); it != events.MemberEnd(); ++it) {
+            Event event;
+            const Value& ev = it->value;
+
+            if (ev.HasMember("description") && ev["description"].IsString())
+                event.description = ev["description"].GetString();
+            if (ev.HasMember("id") && ev["id"].IsUint64())
+                event.id = ev["id"].GetUint64();
+            if (ev.HasMember("logo") && ev["logo"].IsString())
+                event.logo = ev["logo"].GetString();
+            if (ev.HasMember("name") && ev["name"].IsString())
+                event.name = ev["name"].GetString();
+            if (ev.HasMember("subjectCode") && ev["subjectCode"].IsString())
+                event.subjectCode = ev["subjectCode"].GetString();
+            if (ev.HasMember("subtitle") && ev["subtitle"].IsString())
+                event.subtitle = ev["subtitle"].GetString();
+
+            if (ev.HasMember("topicIds") && ev["topicIds"].IsArray()) {
+                const Value& topics = ev["topicIds"];
+                for (SizeType j = 0; j < topics.Size(); j++) {
+                    if (topics[j].IsUint64())
+                        event.topicIds.push_back(topics[j].GetUint64());
+                }
+            }
+
+            if (ev.HasMember("subTopicIds") && ev["subTopicIds"].IsArray()) {
+                const Value& subtopics = ev["subTopicIds"];
+                for (SizeType j = 0; j < subtopics.Size(); j++) {
+                    if (subtopics[j].IsUint64())
+                        event.subTopicIds.push_back(subtopics[j].GetUint64());
+                }
+            }
+
+            catalog.events[it->name.GetString()] = event;
+        }
+    }
+
+    // Parse performances
+    if (doc.HasMember("performances") && doc["performances"].IsArray()) {
+        const Value& performances = doc["performances"];
+        for (SizeType i = 0; i < performances.Size(); i++) {
+            Performance perf;
+            const Value& p = performances[i];
+
+            if (p.HasMember("id") && p["id"].IsUint64())
+                perf.id = p["id"].GetUint64();
+            if (p.HasMember("eventId") && p["eventId"].IsUint64())
+                perf.eventId = p["eventId"].GetUint64();
+            if (p.HasMember("start") && p["start"].IsUint64())
+                perf.start = p["start"].GetUint64();
+            if (p.HasMember("venueCode") && p["venueCode"].IsString())
+                perf.venueCode = p["venueCode"].GetString();
+            if (p.HasMember("name") && p["name"].IsString())
+                perf.name = p["name"].GetString();
+
+            catalog.performances.push_back(perf);
+        }
+    }
+
+    // Parse other string maps
+    auto parseStringMap = [&doc](const char* key, std::map<std::string, std::string>& target) {
+        if (doc.HasMember(key) && doc[key].IsObject()) {
+            const Value& obj = doc[key];
+            for (auto it = obj.MemberBegin(); it != obj.MemberEnd(); ++it) {
+                if (it->value.IsString()) {
+                    target[it->name.GetString()] = it->value.GetString();
+                }
+            }
+        }
+    };
+
+    return catalog;
+}
+
+// RapidJSON serialization for CITM Catalog data
+std::string rapidjson_serialize_citm(const CitmCatalog& catalog) {
+    Document doc;
+    doc.SetObject();
+    Document::AllocatorType& allocator = doc.GetAllocator();
+
+    // Serialize events
+    Value events_obj(kObjectType);
+    for (const auto& [key, event] : catalog.events) {
+        Value event_obj(kObjectType);
+
+        if (event.description) {
+            Value desc;
+            desc.SetString(event.description->c_str(), allocator);
+            event_obj.AddMember("description", desc, allocator);
+        }
+
+        event_obj.AddMember("id", event.id, allocator);
+
+        if (event.logo) {
+            Value logo;
+            logo.SetString(event.logo->c_str(), allocator);
+            event_obj.AddMember("logo", logo, allocator);
+        }
+
+        Value name;
+        name.SetString(event.name.c_str(), allocator);
+        event_obj.AddMember("name", name, allocator);
+
+        if (event.subjectCode) {
+            Value subject;
+            subject.SetString(event.subjectCode->c_str(), allocator);
+            event_obj.AddMember("subjectCode", subject, allocator);
+        }
+
+        if (event.subtitle) {
+            Value subtitle;
+            subtitle.SetString(event.subtitle->c_str(), allocator);
+            event_obj.AddMember("subtitle", subtitle, allocator);
+        }
+
+        Value topicIds(kArrayType);
+        for (uint64_t id : event.topicIds) {
+            topicIds.PushBack(id, allocator);
+        }
+        event_obj.AddMember("topicIds", topicIds, allocator);
+
+        Value subTopicIds(kArrayType);
+        for (uint64_t id : event.subTopicIds) {
+            subTopicIds.PushBack(id, allocator);
+        }
+        event_obj.AddMember("subTopicIds", subTopicIds, allocator);
+
+        Value key_val;
+        key_val.SetString(key.c_str(), allocator);
+        events_obj.AddMember(key_val, event_obj, allocator);
+    }
+    doc.AddMember("events", events_obj, allocator);
+
+    // Serialize performances
+    Value performances_array(kArrayType);
+    for (const auto& perf : catalog.performances) {
+        Value perf_obj(kObjectType);
+        perf_obj.AddMember("id", perf.id, allocator);
+        perf_obj.AddMember("eventId", perf.eventId, allocator);
+        perf_obj.AddMember("start", perf.start, allocator);
+
+        Value venue;
+        venue.SetString(perf.venueCode.c_str(), allocator);
+        perf_obj.AddMember("venueCode", venue, allocator);
+
+        if (perf.name) {
+            Value name;
+            name.SetString(perf.name->c_str(), allocator);
+            perf_obj.AddMember("name", name, allocator);
+        }
+
+
+        performances_array.PushBack(perf_obj, allocator);
+    }
+    doc.AddMember("performances", performances_array, allocator);
+
+    StringBuffer buffer;
+    Writer<StringBuffer> writer(buffer);
+    doc.Accept(writer);
+
+    return buffer.GetString();
+}
+
+#endif // RAPIDJSON_CITM_CATALOG_DATA_H

benchmark/static_reflect/citm_catalog_benchmark/yyjson_citm_catalog_data.h

@@ -0,0 +1,231 @@
+#ifndef YYJSON_CITM_CATALOG_DATA_H
+#define YYJSON_CITM_CATALOG_DATA_H
+
+#include "citm_catalog_data.h"
+#include <yyjson.h>
+#include <string>
+#include <stdexcept>
+
+// yyjson deserialization for CITM Catalog data
+// Matches C++ CitmCatalog struct (only events + performances)
+CitmCatalog yyjson_deserialize_citm(const std::string &json_str) {
+    CitmCatalog catalog;
+
+    yyjson_doc *doc = yyjson_read(json_str.c_str(), json_str.size(), 0);
+    if (!doc) {
+        throw std::runtime_error("yyjson parse error");
+    }
+
+    yyjson_val *root = yyjson_doc_get_root(doc);
+    if (!root) {
+        yyjson_doc_free(doc);
+        return catalog;
+    }
+
+    // Parse events
+    yyjson_val *events_val = yyjson_obj_get(root, "events");
+    if (events_val && yyjson_is_obj(events_val)) {
+        size_t idx, max;
+        yyjson_val *key, *val;
+        yyjson_obj_foreach(events_val, idx, max, key, val) {
+            CITMEvent event;
+
+            yyjson_val *v;
+            v = yyjson_obj_get(val, "description");
+            if (v && yyjson_is_str(v)) event.description = yyjson_get_str(v);
+
+            v = yyjson_obj_get(val, "id");
+            if (v && yyjson_is_uint(v)) event.id = yyjson_get_uint(v);
+
+            v = yyjson_obj_get(val, "logo");
+            if (v && yyjson_is_str(v)) event.logo = yyjson_get_str(v);
+
+            v = yyjson_obj_get(val, "name");
+            if (v && yyjson_is_str(v)) event.name = yyjson_get_str(v);
+
+            v = yyjson_obj_get(val, "subjectCode");
+            if (v && yyjson_is_str(v)) event.subjectCode = yyjson_get_str(v);
+
+            v = yyjson_obj_get(val, "subtitle");
+            if (v && yyjson_is_str(v)) event.subtitle = yyjson_get_str(v);
+
+            // Parse topicIds array
+            v = yyjson_obj_get(val, "topicIds");
+            if (v && yyjson_is_arr(v)) {
+                size_t arr_idx, arr_max;
+                yyjson_val *arr_val;
+                yyjson_arr_foreach(v, arr_idx, arr_max, arr_val) {
+                    if (yyjson_is_uint(arr_val))
+                        event.topicIds.push_back(yyjson_get_uint(arr_val));
+                }
+            }
+
+            // Parse subTopicIds array
+            v = yyjson_obj_get(val, "subTopicIds");
+            if (v && yyjson_is_arr(v)) {
+                size_t arr_idx, arr_max;
+                yyjson_val *arr_val;
+                yyjson_arr_foreach(v, arr_idx, arr_max, arr_val) {
+                    if (yyjson_is_uint(arr_val))
+                        event.subTopicIds.push_back(yyjson_get_uint(arr_val));
+                }
+            }
+
+            if (yyjson_is_str(key))
+                catalog.events[yyjson_get_str(key)] = event;
+        }
+    }
+
+    // Parse performances (simplified - full parsing would need prices/seatCategories)
+    yyjson_val *performances_val = yyjson_obj_get(root, "performances");
+    if (performances_val && yyjson_is_arr(performances_val)) {
+        size_t idx, max;
+        yyjson_val *perf_val;
+        yyjson_arr_foreach(performances_val, idx, max, perf_val) {
+            CITMPerformance perf;
+
+            yyjson_val *v;
+            v = yyjson_obj_get(perf_val, "id");
+            if (v && yyjson_is_uint(v)) perf.id = yyjson_get_uint(v);
+
+            v = yyjson_obj_get(perf_val, "eventId");
+            if (v && yyjson_is_uint(v)) perf.eventId = yyjson_get_uint(v);
+
+            v = yyjson_obj_get(perf_val, "start");
+            if (v && yyjson_is_uint(v)) perf.start = yyjson_get_uint(v);
+
+            v = yyjson_obj_get(perf_val, "venueCode");
+            if (v && yyjson_is_str(v)) perf.venueCode = yyjson_get_str(v);
+
+            v = yyjson_obj_get(perf_val, "name");
+            if (v && yyjson_is_str(v)) perf.name = yyjson_get_str(v);
+
+            v = yyjson_obj_get(perf_val, "logo");
+            if (v && yyjson_is_str(v)) perf.logo = yyjson_get_str(v);
+
+            v = yyjson_obj_get(perf_val, "seatMapImage");
+            if (v && yyjson_is_str(v)) perf.seatMapImage = yyjson_get_str(v);
+
+            // Note: prices and seatCategories parsing omitted for brevity
+            // The serialization benchmark uses data loaded by simdjson
+
+            catalog.performances.push_back(perf);
+        }
+    }
+
+    yyjson_doc_free(doc);
+    return catalog;
+}
+
+// Helper to add optional string field
+static inline void yyjson_add_optional_str(yyjson_mut_doc *doc, yyjson_mut_val *obj,
+                                           const char *key, const std::optional<std::string> &val) {
+    if (val.has_value()) {
+        yyjson_mut_obj_add_str(doc, obj, key, val->c_str());
+    } else {
+        yyjson_mut_obj_add_null(doc, obj, key);
+    }
+}
+
+// yyjson serialization for CITM Catalog data
+// Matches C++ CitmCatalog struct exactly (only events + performances)
+std::string yyjson_serialize_citm(const CitmCatalog &catalog) {
+    yyjson_mut_doc *doc = yyjson_mut_doc_new(NULL);
+    yyjson_mut_val *root = yyjson_mut_obj(doc);
+    yyjson_mut_doc_set_root(doc, root);
+
+    // Create events object
+    yyjson_mut_val *events_obj = yyjson_mut_obj(doc);
+    for (const auto& [key, event] : catalog.events) {
+        yyjson_mut_val *event_obj = yyjson_mut_obj(doc);
+
+        yyjson_add_optional_str(doc, event_obj, "description", event.description);
+        yyjson_mut_obj_add_uint(doc, event_obj, "id", event.id);
+        yyjson_add_optional_str(doc, event_obj, "logo", event.logo);
+        // name is not optional in CITMEvent
+        yyjson_mut_obj_add_str(doc, event_obj, "name", event.name.c_str());
+
+        // Add subTopicIds array
+        yyjson_mut_val *subtopic_ids = yyjson_mut_arr(doc);
+        for (uint64_t id : event.subTopicIds) {
+            yyjson_mut_arr_add_uint(doc, subtopic_ids, id);
+        }
+        yyjson_mut_obj_add_val(doc, event_obj, "subTopicIds", subtopic_ids);
+
+        yyjson_add_optional_str(doc, event_obj, "subjectCode", event.subjectCode);
+        yyjson_add_optional_str(doc, event_obj, "subtitle", event.subtitle);
+
+        // Add topicIds array
+        yyjson_mut_val *topic_ids = yyjson_mut_arr(doc);
+        for (uint64_t id : event.topicIds) {
+            yyjson_mut_arr_add_uint(doc, topic_ids, id);
+        }
+        yyjson_mut_obj_add_val(doc, event_obj, "topicIds", topic_ids);
+
+        yyjson_mut_obj_add_val(doc, events_obj, key.c_str(), event_obj);
+    }
+    yyjson_mut_obj_add_val(doc, root, "events", events_obj);
+
+    // Create performances array
+    yyjson_mut_val *performances_array = yyjson_mut_arr(doc);
+    for (const auto& perf : catalog.performances) {
+        yyjson_mut_val *perf_obj = yyjson_mut_obj(doc);
+
+        yyjson_mut_obj_add_uint(doc, perf_obj, "eventId", perf.eventId);
+        yyjson_mut_obj_add_uint(doc, perf_obj, "id", perf.id);
+        yyjson_add_optional_str(doc, perf_obj, "logo", perf.logo);
+        yyjson_add_optional_str(doc, perf_obj, "name", perf.name);
+
+        // Add prices array
+        yyjson_mut_val *prices_array = yyjson_mut_arr(doc);
+        for (const auto& price : perf.prices) {
+            yyjson_mut_val *price_obj = yyjson_mut_obj(doc);
+            yyjson_mut_obj_add_uint(doc, price_obj, "amount", price.amount);
+            yyjson_mut_obj_add_uint(doc, price_obj, "audienceSubCategoryId", price.audienceSubCategoryId);
+            yyjson_mut_obj_add_uint(doc, price_obj, "seatCategoryId", price.seatCategoryId);
+            yyjson_mut_arr_append(prices_array, price_obj);
+        }
+        yyjson_mut_obj_add_val(doc, perf_obj, "prices", prices_array);
+
+        // Add seatCategories array
+        yyjson_mut_val *seat_cats_array = yyjson_mut_arr(doc);
+        for (const auto& seatCat : perf.seatCategories) {
+            yyjson_mut_val *seat_cat_obj = yyjson_mut_obj(doc);
+
+            // Add areas array
+            yyjson_mut_val *areas_array = yyjson_mut_arr(doc);
+            for (const auto& area : seatCat.areas) {
+                yyjson_mut_val *area_obj = yyjson_mut_obj(doc);
+                yyjson_mut_obj_add_uint(doc, area_obj, "areaId", area.areaId);
+
+                yyjson_mut_val *block_ids = yyjson_mut_arr(doc);
+                for (uint64_t blockId : area.blockIds) {
+                    yyjson_mut_arr_add_uint(doc, block_ids, blockId);
+                }
+                yyjson_mut_obj_add_val(doc, area_obj, "blockIds", block_ids);
+                yyjson_mut_arr_append(areas_array, area_obj);
+            }
+            yyjson_mut_obj_add_val(doc, seat_cat_obj, "areas", areas_array);
+            yyjson_mut_obj_add_uint(doc, seat_cat_obj, "seatCategoryId", seatCat.seatCategoryId);
+            yyjson_mut_arr_append(seat_cats_array, seat_cat_obj);
+        }
+        yyjson_mut_obj_add_val(doc, perf_obj, "seatCategories", seat_cats_array);
+
+        yyjson_add_optional_str(doc, perf_obj, "seatMapImage", perf.seatMapImage);
+        yyjson_mut_obj_add_uint(doc, perf_obj, "start", perf.start);
+        yyjson_mut_obj_add_str(doc, perf_obj, "venueCode", perf.venueCode.c_str());
+
+        yyjson_mut_arr_append(performances_array, perf_obj);
+    }
+    yyjson_mut_obj_add_val(doc, root, "performances", performances_array);
+
+    // Write to string
+    char *json_output = yyjson_mut_write(doc, 0, NULL);
+    std::string result(json_output);
+    free(json_output);
+    yyjson_mut_doc_free(doc);
+
+    return result;
+}
+
+#endif // YYJSON_CITM_CATALOG_DATA_H

benchmark/static_reflect/serde-benchmark/lib.rs

@@ -5,405 +5,165 @@ 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,
-}
+//==============================================================================
+// Twitter Benchmark Structures
+// These match the C++ TwitterData structures exactly
+//==============================================================================
 
 #[derive(Serialize, Deserialize)]
 pub struct User {
-    id: i64,
-    id_str: String,
+    id: u64,
     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>,
+    followers_count: u64,
+    friends_count: u64,
+    statuses_count: u64,
 }
 
 #[derive(Serialize, Deserialize)]
 pub struct Status {
     created_at: String,
-    id: i64,
+    id: u64,
     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,
-    */
+    retweet_count: u64,
+    favorite_count: u64,
 }
 
 #[derive(Serialize, Deserialize)]
 pub struct TwitterData {
     statuses: Vec<Status>,
 }
+static mut TWITTER_DATA: *mut TwitterData = std::ptr::null_mut();
 
 #[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(),
-  }
+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()
+pub unsafe extern "C" fn set_twitter_data(raw: *mut TwitterData) {
+    TWITTER_DATA = raw;
 }
 
+#[no_mangle]
+pub unsafe extern "C" fn serialize_twitter_to_string() -> usize {
+    if TWITTER_DATA.is_null() {
+        return 0;
+    }
+    let data = &*TWITTER_DATA;
+    serde_json::to_string(data).unwrap().len()
+}
 
 #[no_mangle]
 pub unsafe extern "C" fn free_twitter(raw: *mut TwitterData) {
-  if raw.is_null() {
-    return;
-  }
-
-  drop(Box::from_raw(raw))
+    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
+//==============================================================================
+// CITM Catalog Benchmark Structures
+// These match the C++ CitmCatalog structures EXACTLY for fair comparison
+//==============================================================================
 
-#[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>,
+/// Matches C++ CITMPrice struct exactly
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct CITMPrice {
+    pub amount: u64,
+    #[serde(rename = "audienceSubCategoryId")]
+    pub audience_sub_category_id: u64,
+    #[serde(rename = "seatCategoryId")]
+    pub seat_category_id: u64,
 }
 
-#[derive(Serialize, Deserialize)]
-pub struct AudienceSubCategory {
-    pub id: i64,
-    pub name: Option<String>,  // Changed to Option
-    pub parent: i64,
+/// Matches C++ CITMArea struct exactly
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct CITMArea {
+    #[serde(rename = "areaId")]
+    pub area_id: u64,
+    #[serde(rename = "blockIds")]
+    pub block_ids: Vec<u64>,
 }
 
-#[derive(Serialize, Deserialize, Debug)]
-pub struct Event {
-    #[serde(default)]
-    pub description: Option<String>,
-    pub id: i64,
+/// Matches C++ CITMSeatCategory struct exactly
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct CITMSeatCategory {
+    pub areas: Vec<CITMArea>,
+    #[serde(rename = "seatCategoryId")]
+    pub seat_category_id: u64,
+}
+
+/// Matches C++ CITMPerformance struct exactly
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct CITMPerformance {
+    pub id: u64,
+    #[serde(rename = "eventId")]
+    pub event_id: u64,
     #[serde(default)]
     pub logo: Option<String>,
     #[serde(default)]
     pub name: Option<String>,
+    pub prices: Vec<CITMPrice>,
+    #[serde(rename = "seatCategories")]
+    pub seat_categories: Vec<CITMSeatCategory>,
     #[serde(default)]
-    pub subTopicIds: Vec<i64>,
+    #[serde(rename = "seatMapImage")]
+    pub seat_map_image: Option<String>,
+    pub start: u64,
+    #[serde(rename = "venueCode")]
+    pub venue_code: String,
+}
+
+/// Matches C++ CITMEvent struct exactly
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct CITMEvent {
+    pub id: u64,
     #[serde(default)]
-    pub subjectCode: Option<String>,
+    pub name: Option<String>,
+    #[serde(default)]
+    pub description: Option<String>,
+    #[serde(default)]
+    pub logo: Option<String>,
+    #[serde(default)]
+    #[serde(rename = "subTopicIds")]
+    pub sub_topic_ids: Vec<u64>,
+    #[serde(default)]
+    #[serde(rename = "subjectCode")]
+    pub subject_code: 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)
+    #[serde(rename = "topicIds")]
+    pub topic_ids: Vec<u64>,
 }
 
+/// Matches C++ CitmCatalog struct exactly - ONLY events and performances
+/// This is the key fix: we serialize only what C++ serializes
 #[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>,
+    pub events: HashMap<String, CITMEvent>,
+    pub performances: Vec<CITMPerformance>,
 }
 
+static mut CITM_DATA: *mut CitmCatalog = std::ptr::null_mut();
+
 /// Creates a CitmCatalog from a JSON string (UTF-8 encoded).
+/// Only extracts events and performances to match C++ behavior.
 #[no_mangle]
 pub unsafe extern "C" fn citm_from_str(
     raw_input: *const c_char,
@@ -414,7 +174,6 @@ pub unsafe extern "C" fn citm_from_str(
         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,
@@ -424,12 +183,23 @@ pub unsafe extern "C" fn citm_from_str(
         }
     };
 
-    // Try deserializing the input string into CitmCatalog
-    match serde_json::from_str::<CitmCatalog>(input_str) {
-        Ok(catalog) => Box::into_raw(Box::new(catalog)),
+    // Parse the full JSON to extract only events and performances
+    match serde_json::from_str::<serde_json::Value>(input_str) {
+        Ok(full_json) => {
+            // Extract only the fields we need (matching C++ behavior)
+            let events: HashMap<String, CITMEvent> = full_json.get("events")
+                .and_then(|v| serde_json::from_value(v.clone()).ok())
+                .unwrap_or_default();
+
+            let performances: Vec<CITMPerformance> = full_json.get("performances")
+                .and_then(|v| serde_json::from_value(v.clone()).ok())
+                .unwrap_or_default();
+
+            let catalog = CitmCatalog { events, performances };
+            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()
         }
     }
@@ -437,30 +207,17 @@ pub unsafe extern "C" fn citm_from_str(
 
 /// 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();
-    }
+pub unsafe extern "C" fn set_citm_data(raw: *mut CitmCatalog) {
+    CITM_DATA = raw;
+}
 
-    // 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()
-        }
+#[no_mangle]
+pub unsafe extern "C" fn serialize_citm_to_string() -> usize {
+    if CITM_DATA.is_null() {
+        return 0;
     }
+    let data = &*CITM_DATA;
+    return serde_json::to_string(data).unwrap().len();
 }
 
 /// Frees the CitmCatalog pointer.
@@ -475,8 +232,120 @@ pub unsafe extern "C" fn free_citm(raw_catalog: *mut CitmCatalog) {
 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);
         }
     }
-}
+}
+
+//==============================================================================
+// FFI Overhead Measurement Functions
+// These allow measuring the actual FFI overhead vs pure Rust serialization
+//==============================================================================
+
+/// Result structure for FFI overhead measurement
+#[repr(C)]
+pub struct FfiOverheadResult {
+    /// Time in nanoseconds for pure serde_json::to_string() (no FFI overhead)
+    pub pure_serde_ns: u64,
+    /// Time in nanoseconds for serde + CString conversion
+    pub serde_plus_cstring_ns: u64,
+    /// Number of iterations performed
+    pub iterations: u64,
+    /// Output size in bytes (for verification)
+    pub output_size: u64,
+}
+
+/// Prevents compiler from optimizing away the value
+/// Works on stable Rust (unlike std::hint::black_box which is unstable)
+#[inline(never)]
+fn black_box<T>(dummy: T) -> T {
+    unsafe {
+        let ret = std::ptr::read_volatile(&dummy);
+        std::mem::forget(dummy);
+        ret
+    }
+}
+
+/// Measures FFI overhead for Twitter serialization.
+/// Performs `iterations` serializations entirely in Rust and returns timing data.
+/// This allows comparing against per-call FFI overhead.
+#[no_mangle]
+pub unsafe extern "C" fn measure_twitter_ffi_overhead(
+    raw: *mut TwitterData,
+    iterations: u64
+) -> FfiOverheadResult {
+    use std::time::Instant;
+
+    let twitter_data = &*raw;
+    let output_size: u64;
+
+    // Warm-up run
+    let warmup = serde_json::to_string(&twitter_data).unwrap();
+    output_size = warmup.len() as u64;
+
+    // Measure pure serde_json::to_string() - no CString conversion
+    let start_pure = Instant::now();
+    for _ in 0..iterations {
+        let serialized = serde_json::to_string(&twitter_data).unwrap();
+        // Prevent optimization from eliminating the work
+        black_box(&serialized);
+    }
+    let pure_serde_ns = start_pure.elapsed().as_nanos() as u64;
+
+    // Measure serde + CString conversion (but not FFI return)
+    let start_cstring = Instant::now();
+    for _ in 0..iterations {
+        let serialized = serde_json::to_string(&twitter_data).unwrap();
+        let cstring = CString::new(serialized).unwrap();
+        // Prevent optimization from eliminating the work
+        black_box(&cstring);
+    }
+    let serde_plus_cstring_ns = start_cstring.elapsed().as_nanos() as u64;
+
+    FfiOverheadResult {
+        pure_serde_ns,
+        serde_plus_cstring_ns,
+        iterations,
+        output_size,
+    }
+}
+
+/// Measures FFI overhead for CITM serialization.
+#[no_mangle]
+pub unsafe extern "C" fn measure_citm_ffi_overhead(
+    raw: *mut CitmCatalog,
+    iterations: u64
+) -> FfiOverheadResult {
+    use std::time::Instant;
+
+    let catalog = &*raw;
+    let output_size: u64;
+
+    // Warm-up run
+    let warmup = serde_json::to_string(&catalog).unwrap();
+    output_size = warmup.len() as u64;
+
+    // Measure pure serde_json::to_string() - no CString conversion
+    let start_pure = Instant::now();
+    for _ in 0..iterations {
+        let serialized = serde_json::to_string(&catalog).unwrap();
+        black_box(&serialized);
+    }
+    let pure_serde_ns = start_pure.elapsed().as_nanos() as u64;
+
+    // Measure serde + CString conversion
+    let start_cstring = Instant::now();
+    for _ in 0..iterations {
+        let serialized = serde_json::to_string(&catalog).unwrap();
+        let cstring = CString::new(serialized).unwrap();
+        black_box(&cstring);
+    }
+    let serde_plus_cstring_ns = start_cstring.elapsed().as_nanos() as u64;
+
+    FfiOverheadResult {
+        pure_serde_ns,
+        serde_plus_cstring_ns,
+        iterations,
+        output_size,
+    }
+}

benchmark/static_reflect/serde-benchmark/serde_benchmark.h

@@ -4,6 +4,7 @@
 /* Generated with cbindgen:0.28.0 */
 
 /* Warning, this file is autogenerated by cbindgen. Don't modify this manually. */
+/* Note: FfiOverheadResult and measurement functions added manually */
 
 #include <cstdarg>
 #include <cstdint>
@@ -17,11 +18,25 @@ struct CitmCatalog;
 
 struct TwitterData;
 
+/// Result structure for FFI overhead measurement
+struct FfiOverheadResult {
+    /// Time in nanoseconds for pure serde_json::to_string() (no FFI overhead)
+    uint64_t pure_serde_ns;
+    /// Time in nanoseconds for serde + CString conversion
+    uint64_t serde_plus_cstring_ns;
+    /// Number of iterations performed
+    uint64_t iterations;
+    /// Output size in bytes (for verification)
+    uint64_t output_size;
+};
+
 extern "C" {
 
 TwitterData *twitter_from_str(const char *raw_input, size_t raw_input_length);
 
-const char *str_from_twitter(TwitterData *raw);
+void set_twitter_data(TwitterData *raw);
+
+size_t serialize_twitter_to_string();
 
 void free_twitter(TwitterData *raw);
 
@@ -30,14 +45,22 @@ 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);
+void set_citm_data(CitmCatalog *raw);
+
+size_t serialize_citm_to_string();
 
 /// Frees the CitmCatalog pointer.
 void free_citm(CitmCatalog *raw_catalog);
 
 void free_str(char *ptr);
 
+/// Measures FFI overhead for Twitter serialization.
+/// Performs `iterations` serializations entirely in Rust and returns timing data.
+FfiOverheadResult measure_twitter_ffi_overhead(TwitterData *raw, uint64_t iterations);
+
+/// Measures FFI overhead for CITM serialization.
+FfiOverheadResult measure_citm_ffi_overhead(CitmCatalog *raw, uint64_t iterations);
+
 }  // extern "C"
 
 }  // namespace serde_benchmark

benchmark/static_reflect/serde-benchmark/src/main.rs

@@ -0,0 +1,31 @@
+use std::fs;
+
+// Include the lib.rs content directly
+include!("../lib.rs");
+
+fn main() {
+    // Read the Twitter JSON file
+    let json_str = fs::read_to_string("/Users/random_person/Desktop/simdjson/build/jsonexamples/twitter.json")
+        .expect("Failed to read file");
+
+    // Parse it
+    let data: TwitterData = serde_json::from_str(&json_str)
+        .expect("Failed to parse JSON");
+
+    // Serialize it back
+    let output = serde_json::to_string(&data)
+        .expect("Failed to serialize");
+
+    // Write to file for comparison
+    fs::write("rust_output.json", &output)
+        .expect("Failed to write output");
+
+    println!("Output size: {} bytes", output.len());
+    println!("Written to rust_output.json");
+
+    // Also write pretty version for easier inspection
+    let pretty = serde_json::to_string_pretty(&data)
+        .expect("Failed to serialize pretty");
+    fs::write("rust_output_pretty.json", &pretty)
+        .expect("Failed to write pretty output");
+}

benchmark/static_reflect/serde-benchmark/src/test_output.rs

@@ -0,0 +1,36 @@
+use std::fs;
+
+// Import from the parent lib.rs
+include!("../lib.rs");
+
+fn main() {
+    // Read the Twitter JSON file
+    let json_str = fs::read_to_string("/Users/random_person/Desktop/simdjson/build/jsonexamples/twitter.json")
+        .expect("Failed to read file");
+
+    // Parse it
+    let data: TwitterData = serde_json::from_str(&json_str)
+        .expect("Failed to parse JSON");
+
+    // Serialize it back (compact)
+    let output = serde_json::to_vec(&data)
+        .expect("Failed to serialize");
+    
+    let output_str = String::from_utf8(output.clone()).unwrap();
+
+    // Write to file for comparison
+    fs::write("rust_output_test.json", &output)
+        .expect("Failed to write output");
+
+    println!("Output size: {} bytes", output.len());
+    
+    // Count statuses
+    println!("Number of statuses: {}", data.statuses.len());
+    
+    // Check what fields are in the first status
+    if let Some(first) = data.statuses.first() {
+        // Let's serialize just the first status to see what fields are included
+        let first_json = serde_json::to_string_pretty(first).unwrap();
+        println!("First status (pretty):\n{}", first_json);
+    }
+}

benchmark/static_reflect/twitter_benchmark/CMakeLists.txt

@@ -1,14 +1,32 @@
 
 # Add executable targets
 add_executable(benchmark_serialization_twitter benchmark_serialization_twitter.cpp)
+add_executable(benchmark_parsing_twitter benchmark_parsing_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_link_libraries(benchmark_parsing_twitter PRIVATE serde-benchmark)
     target_compile_definitions(benchmark_serialization_twitter PRIVATE SIMDJSON_RUST_VERSION="${Rust_VERSION}")
+    target_compile_definitions(benchmark_parsing_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}")
+target_link_libraries(benchmark_parsing_twitter PRIVATE simdjson::simdjson nlohmann_json)
+
+if(TARGET rapidjson)
+    target_link_libraries(benchmark_parsing_twitter PRIVATE rapidjson)
+    target_compile_definitions(benchmark_parsing_twitter PRIVATE SIMDJSON_COMPETITION_RAPIDJSON)
+endif()
+
+if(TARGET yyjson)
+    target_link_libraries(benchmark_parsing_twitter PRIVATE yyjson)
+    target_compile_definitions(benchmark_parsing_twitter PRIVATE SIMDJSON_COMPETITION_YYJSON)
+    target_link_libraries(benchmark_serialization_twitter PRIVATE yyjson)
+    target_compile_definitions(benchmark_serialization_twitter PRIVATE SIMDJSON_COMPETITION_YYJSON)
+endif()
+
+target_compile_definitions(benchmark_serialization_twitter PRIVATE JSON_FILE="${EXAMPLE_JSON}")
+target_compile_definitions(benchmark_parsing_twitter PRIVATE JSON_FILE="${EXAMPLE_JSON}")

benchmark/static_reflect/twitter_benchmark/benchmark_parsing_twitter.cpp

@@ -0,0 +1,232 @@
+#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"
+#ifdef SIMDJSON_COMPETITION_RAPIDJSON
+#include "rapidjson_twitter_data.h"
+#endif
+#ifdef SIMDJSON_COMPETITION_YYJSON
+#include "yyjson_twitter_data.h"
+#endif
+
+#ifdef SIMDJSON_RUST_VERSION
+#include "../serde-benchmark/serde_benchmark.h"
+
+void bench_rust_parsing(const std::string &json_str) {
+  size_t input_volume = json_str.size();
+  printf("# input volume: %zu bytes\n", input_volume);
+
+  volatile bool result = true;
+  pretty_print(1, input_volume, "bench_rust_parsing",
+               bench([&json_str, &result]() {
+                 serde_benchmark::TwitterData *td = serde_benchmark::twitter_from_str(json_str.c_str(), json_str.size());
+                 result = (td != nullptr);
+                 if (td) {
+                   serde_benchmark::free_twitter(td);
+                 }
+                 if (!result) {
+                   printf("parse error\n");
+                 }
+               }));
+}
+#endif
+
+// OPTIMIZED VERSION: Reuses parser across iterations
+template <class T>
+void bench_simdjson_static_reflection_parsing(const std::string &json_str) {
+  size_t input_volume = json_str.size();
+  printf("# input volume: %zu bytes\n", input_volume);
+
+  // Pre-allocate padded buffer outside the benchmark loop
+  simdjson::padded_string padded = simdjson::padded_string(json_str);
+
+  // CRITICAL: Create parser OUTSIDE the loop for reuse
+  simdjson::ondemand::parser parser;
+
+  volatile bool result = true;
+  pretty_print(1, input_volume, "bench_simdjson_static_reflection_parsing",
+               bench([&padded, &result, &parser]() {
+                 // Reuse the same parser instance
+                 simdjson::ondemand::document doc;
+                 if(parser.iterate(padded).get(doc)) {
+                   result = false;
+                   return;
+                 }
+                 T my_struct;
+                 if(doc.get<T>().get(my_struct)) {
+                   result = false;
+                 }
+                 if (!result) {
+                   printf("parse error\n");
+                 }
+               }));
+}
+
+#if SIMDJSON_STATIC_REFLECTION
+template <class T>
+void bench_simdjson_from_parsing(const std::string &json_str) {
+  size_t input_volume = json_str.size();
+  printf("# input volume: %zu bytes\n", input_volume);
+
+  // Pre-allocate padded buffer outside the benchmark loop
+  simdjson::padded_string padded = simdjson::padded_string(json_str);
+
+  volatile bool result = true;
+  pretty_print(1, input_volume, "bench_simdjson_from_parsing",
+               bench([&padded, &result]() {
+                 T my_struct;
+                 auto err = simdjson::from(padded).get(my_struct);
+                  if (err) {
+                    result = false;
+                    printf("parse error: %s\n", simdjson::error_message(err));
+                    return;
+                  }
+               }));
+}
+#endif
+
+ void bench_nlohmann_parsing(const std::string &json_str) {
+   size_t input_volume = json_str.size();
+   printf("# input volume: %zu bytes\n", input_volume);
+
+   volatile bool result = true;
+   pretty_print(1, input_volume, "bench_nlohmann_parsing",
+                bench([&json_str, &result]() {
+                  try {
+                    TwitterData data = nlohmann_deserialize(json_str);
+                    result = true;
+                  } catch (...) {
+                    result = false;
+                    printf("parse error\n");
+                  }
+                }));
+}
+
+#ifdef SIMDJSON_COMPETITION_RAPIDJSON
+void bench_rapidjson_parsing(const std::string &json_str) {
+  size_t input_volume = json_str.size();
+  printf("# input volume: %zu bytes\n", input_volume);
+
+  volatile bool result = true;
+  pretty_print(1, input_volume, "bench_rapidjson_parsing",
+               bench([&json_str, &result]() {
+                 try {
+                   TwitterData data = rapidjson_deserialize(json_str);
+                   result = true;
+                 } catch (...) {
+                   result = false;
+                   printf("parse error\n");
+                 }
+               }));
+}
+#endif
+
+#ifdef SIMDJSON_COMPETITION_YYJSON
+void bench_yyjson_parsing(const std::string &json_str) {
+  size_t input_volume = json_str.size();
+  printf("# input volume: %zu bytes\n", input_volume);
+
+  volatile bool result = true;
+  pretty_print(1, input_volume, "bench_yyjson_parsing",
+               bench([&json_str, &result]() {
+                 try {
+                   TwitterData data = yyjson_deserialize(json_str);
+                   result = true;
+                 } catch (...) {
+                   result = false;
+                   printf("parse error\n");
+                 }
+               }));
+}
+#endif
+
+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 matches any of the comma-separated filters
+bool matches_filter(const std::string& benchmark_name, const std::string& filter) {
+  if (filter.empty()) return true;
+
+  // Split filter by comma
+  size_t start = 0;
+  size_t end = filter.find(',');
+  while (end != std::string::npos) {
+    std::string token = filter.substr(start, end - start);
+    if (benchmark_name.find(token) != std::string::npos) {
+      return true;
+    }
+    start = end + 1;
+    end = filter.find(',', start);
+  }
+  // Check last token
+  std::string token = filter.substr(start);
+  return benchmark_name.find(token) != 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;
+          }
+      }
+  }
+
+  // Load the JSON data
+  std::string json_str = read_file(JSON_FILE);
+
+  // Benchmarking the parsing
+  if (matches_filter("nlohmann", filter)) {
+    bench_nlohmann_parsing(json_str);
+  }
+#ifdef SIMDJSON_COMPETITION_RAPIDJSON
+  if (matches_filter("rapidjson", filter)) {
+    bench_rapidjson_parsing(json_str);
+  }
+#endif
+#ifdef SIMDJSON_COMPETITION_YYJSON
+  if (matches_filter("yyjson", filter)) {
+    bench_yyjson_parsing(json_str);
+  }
+#endif
+  if (matches_filter("simdjson_static_reflection", filter)) {
+    bench_simdjson_static_reflection_parsing<TwitterData>(json_str);
+  }
+#if SIMDJSON_STATIC_REFLECTION
+  if (matches_filter("simdjson_from", filter)) {
+    bench_simdjson_from_parsing<TwitterData>(json_str);
+  }
+#endif
+#ifdef SIMDJSON_RUST_VERSION
+  if (matches_filter("rust", filter)) {
+    printf("# Note: Rust/Serde parsing test\n");
+    bench_rust_parsing(json_str);
+  }
+#endif
+  return EXIT_SUCCESS;
+}

benchmark/static_reflect/twitter_benchmark/benchmark_serialization_twitter.cpp

@@ -1,4 +1,5 @@
 #include <cassert>
+#include <chrono>
 #include <cstdlib>
 #include <ctime>
 #include <format>
@@ -10,6 +11,9 @@
 #include "twitter_data.h"
 #include "nlohmann_twitter_data.h"
 #include "../benchmark_utils/benchmark_helper.h"
+#ifdef SIMDJSON_COMPETITION_YYJSON
+#include "yyjson_twitter_data.h"
+#endif
 #if SIMDJSON_BENCH_CPP_REFLECT
 #include <rfl.hpp>
 #include <rfl/json.hpp>
@@ -35,19 +39,49 @@ void bench_reflect_cpp(TwitterData &data) {
 
 
 void bench_rust(serde_benchmark::TwitterData *data) {
-  const char * output = serde_benchmark::str_from_twitter(data);
-  size_t output_volume = strlen(output);
+  serde_benchmark::set_twitter_data(data);
+  size_t output_volume = serde_benchmark::serialize_twitter_to_string();
   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);
+               bench([&measured_volume, &output_volume]() {
+                 measured_volume = serde_benchmark::serialize_twitter_to_string();
                }));
 }
 #endif
 
+// Fair allocation variant: allocates fresh buffer each iteration (matches other libraries)
 template <class T> void bench_simdjson_static_reflection(T &data) {
+  // First run to determine expected size
+  simdjson::builder::string_builder sb_init;
+  simdjson::builder::append(sb_init, data);
+  std::string_view p_init;
+  if(sb_init.view().get(p_init)) {
+    std::cerr << "Error!" << std::endl;
+  }
+  size_t output_volume = p_init.size();
+  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]() {
+                 // Fresh allocation each iteration - fair comparison
+                 simdjson::builder::string_builder sb;
+                 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");
+                 }
+               }));
+}
+
+// Optimized variant: reuses buffer across iterations (shows API potential)
+template <class T> void bench_simdjson_static_reflection_reuse(T &data) {
   simdjson::builder::string_builder sb;
   simdjson::builder::append(sb, data);
   std::string_view p;
@@ -59,7 +93,7 @@ template <class T> void bench_simdjson_static_reflection(T &data) {
   printf("# output volume: %zu bytes\n", output_volume);
 
   volatile size_t measured_volume = 0;
-  pretty_print(sizeof(data), output_volume, "bench_simdjson_static_reflection",
+  pretty_print(sizeof(data), output_volume, "bench_simdjson_reuse_buffer",
                bench([&data, &measured_volume, &output_volume, &sb]() {
                  sb.clear();
                  simdjson::builder::append(sb, data);
@@ -74,6 +108,63 @@ template <class T> void bench_simdjson_static_reflection(T &data) {
                }));
 }
 
+#if SIMDJSON_STATIC_REFLECTION
+// Fair allocation variant: allocates fresh string each iteration
+template <class T> void bench_simdjson_to(T &data) {
+  // First run to determine size
+  std::string output_init;
+  if (simdjson::error_code err = simdjson::builder::to_json(data, output_init); err) {
+    std::cerr << "Error in to_json initialization!" << simdjson::error_message(err) << std::endl;
+    return;
+  }
+  size_t output_volume = output_init.size();
+  printf("# output volume: %zu bytes\n", output_volume);
+
+  volatile size_t measured_volume = 0;
+  pretty_print(sizeof(data), output_volume, "bench_simdjson_to",
+               bench([&data, &measured_volume, &output_volume]() {
+                 // Fresh allocation each iteration - fair comparison
+                 std::string output;
+                 if (simdjson::error_code err = simdjson::builder::to_json(data, output); err) {
+                   std::cerr << "Error in to_json!" << simdjson::error_message(err) << std::endl;
+                   return;
+                 }
+                 measured_volume = output.size();
+                 if (measured_volume != output_volume) {
+                   printf("mismatch\n");
+                 }
+               }));
+}
+
+// Optimized variant: reuses pre-allocated string
+template <class T> void bench_simdjson_to_reuse(T &data) {
+  std::string output;
+  if (simdjson::error_code err = simdjson::builder::to_json(data, output); err) {
+    std::cerr << "Error in to_json initialization!" << simdjson::error_message(err) << std::endl;
+    return;
+  }
+  size_t output_volume = output.size();
+  printf("# output volume: %zu bytes\n", output_volume);
+
+  // Pre-allocate string with sufficient capacity to avoid reallocation
+  output.reserve(output_volume * 2);
+
+  volatile size_t measured_volume = 0;
+  pretty_print(sizeof(data), output_volume, "bench_simdjson_to_reuse",
+               bench([&data, &measured_volume, &output_volume, &output]() {
+                 // Reuse the pre-allocated string - avoids allocation
+                 if (simdjson::error_code err = simdjson::builder::to_json(data, output); err) {
+                   std::cerr << "Error in to_json!" << simdjson::error_message(err) << std::endl;
+                   return;
+                 }
+                 measured_volume = output.size();
+                 if (measured_volume != output_volume) {
+                   printf("mismatch\n");
+                 }
+               }));
+}
+#endif
+
 void bench_nlohmann(TwitterData &data) {
   std::string output = nlohmann_serialize(data);
   size_t output_volume = output.size();
@@ -90,28 +181,61 @@ void bench_nlohmann(TwitterData &data) {
                }));
 }
 
+#ifdef SIMDJSON_COMPETITION_YYJSON
+void bench_yyjson(TwitterData &data) {
+  std::string output = yyjson_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_yyjson",
+               bench([&data, &measured_volume, &output_volume]() {
+                 std::string output = yyjson_serialize(data);
+                 measured_volume = output.size();
+                 if (measured_volume != output_volume) {
+                   printf("mismatch\n");
+                 }
+               }));
+}
+#endif
+
 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) {
+simdjson::padded_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;
+  simdjson::padded_string_builder builder;
   std::string buf(read_size, '\0');
   while (stream.read(&buf[0], read_size)) {
-    out.append(buf, 0, size_t(stream.gcount()));
+    builder.append(buf.data(), size_t(stream.gcount()));
   }
-  out.append(buf, 0, size_t(stream.gcount()));
-  return out;
+  builder.append(buf.data(), size_t(stream.gcount()));
+  return builder.convert();
 }
 
-// Function to check if benchmark name contains filter substring
+// Function to check if benchmark name matches any of the comma-separated filters
 bool matches_filter(const std::string& benchmark_name, const std::string& filter) {
-  return filter.empty() || benchmark_name.find(filter) != std::string::npos;
+  if (filter.empty()) return true;
+
+  // Split filter by comma
+  size_t start = 0;
+  size_t end = filter.find(',');
+  while (end != std::string::npos) {
+    std::string token = filter.substr(start, end - start);
+    if (benchmark_name.find(token) != std::string::npos) {
+      return true;
+    }
+    start = end + 1;
+    end = filter.find(',', start);
+  }
+  // Check last token
+  std::string token = filter.substr(start);
+  return benchmark_name.find(token) != std::string::npos;
 }
 
 int main(int argc, char* argv[]) {
@@ -129,12 +253,12 @@ int main(int argc, char* argv[]) {
       }
   }
   // Testing correctness of round-trip (serialization + deserialization)
-  std::string json_str = read_file(JSON_FILE);
+  simdjson::padded_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)) {
+  if(parser.iterate(json_str).get(doc)) {
     std::cerr << "Error loading the document!" << std::endl;
     return EXIT_FAILURE;
   }
@@ -145,18 +269,41 @@ int main(int argc, char* argv[]) {
   }
 
   // Benchmarking the serialization
+  // Note: simdjson benchmarks include both "fair" (fresh allocation) and "reuse" (buffer reuse) variants
+  // The "fair" variants allocate fresh memory each iteration, matching other libraries' behavior
+  // The "reuse" variants demonstrate the API's potential when buffer reuse is possible
+
   if (matches_filter("nlohmann", filter)) {
     bench_nlohmann(my_struct);
   }
+#ifdef SIMDJSON_COMPETITION_YYJSON
+  if (matches_filter("yyjson", filter)) {
+    bench_yyjson(my_struct);
+  }
+#endif
   if (matches_filter("simdjson_static_reflection", filter)) {
     bench_simdjson_static_reflection(my_struct);
   }
+  if (matches_filter("simdjson_reuse", filter)) {
+    bench_simdjson_static_reflection_reuse(my_struct);
+  }
+#if SIMDJSON_STATIC_REFLECTION
+  if (matches_filter("simdjson_to", filter)) {
+    bench_simdjson_to(my_struct);
+  }
+  if (matches_filter("simdjson_to_reuse", filter)) {
+    bench_simdjson_to_reuse(my_struct);
+  }
+#endif
 #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);
+    serde_benchmark::TwitterData * td = serde_benchmark::twitter_from_str(json_str.data(), json_str.size());
+    if (td == nullptr) {
+      printf("# Failed to parse Twitter data for Rust benchmark\n");
+    } else {
+      bench_rust(td);
+      serde_benchmark::free_twitter(td);
+    }
   }
 #endif
 #if SIMDJSON_BENCH_CPP_REFLECT

benchmark/static_reflect/twitter_benchmark/nlohmann_twitter_data.h

@@ -4,6 +4,7 @@
 #include "twitter_data.h"
 #include <nlohmann/json.hpp>
 
+// Serialization functions for nlohmann
 void to_json(nlohmann::json &j, const User &u) {
   j = nlohmann::json{{"id", u.id},
                      {"name", u.name},
@@ -16,101 +17,54 @@ void to_json(nlohmann::json &j, const User &u) {
                      {"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();
+                     {"favorite_count", s.favorite_count}};
 }
 
 void to_json(nlohmann::json &j, const TwitterData &t) {
   j = nlohmann::json{{"statuses", t.statuses}};
 }
 
+// Deserialization functions for nlohmann
+void from_json(const nlohmann::json &j, User &u) {
+  j.at("id").get_to(u.id);
+  j.at("name").get_to(u.name);
+  j.at("screen_name").get_to(u.screen_name);
+  j.at("location").get_to(u.location);
+  j.at("description").get_to(u.description);
+  j.at("verified").get_to(u.verified);
+  j.at("followers_count").get_to(u.followers_count);
+  j.at("friends_count").get_to(u.friends_count);
+  j.at("statuses_count").get_to(u.statuses_count);
+}
+
+void from_json(const nlohmann::json &j, Status &s) {
+  j.at("created_at").get_to(s.created_at);
+  j.at("id").get_to(s.id);
+  j.at("text").get_to(s.text);
+  j.at("user").get_to(s.user);
+  j.at("retweet_count").get_to(s.retweet_count);
+  j.at("favorite_count").get_to(s.favorite_count);
+}
+
+void from_json(const nlohmann::json &j, TwitterData &t) {
+  j.at("statuses").get_to(t.statuses);
+}
+
+// Helper functions for benchmarking
 std::string nlohmann_serialize(const TwitterData &data) {
-  return nlohmann_serialize(data.statuses);
+  nlohmann::json j = data;
+  return j.dump();
+}
+
+TwitterData nlohmann_deserialize(const std::string &json_str) {
+  nlohmann::json j = nlohmann::json::parse(json_str);
+  return j.get<TwitterData>();
 }
 
 #endif // NLOHMANN_TWITTER_DATA_H

benchmark/static_reflect/twitter_benchmark/rapidjson_twitter_data.h

@@ -0,0 +1,142 @@
+#ifndef RAPIDJSON_TWITTER_DATA_H
+#define RAPIDJSON_TWITTER_DATA_H
+
+#include "twitter_data.h"
+#include <rapidjson/document.h>
+#include <rapidjson/writer.h>
+#include <rapidjson/stringbuffer.h>
+#include <rapidjson/error/en.h>
+
+using namespace rapidjson;
+
+// RapidJSON deserialization for simplified Twitter data
+TwitterData rapidjson_deserialize(const std::string& json_str) {
+    Document doc;
+    doc.Parse(json_str.c_str());
+
+    if (doc.HasParseError()) {
+        throw std::runtime_error("RapidJSON parse error");
+    }
+
+    TwitterData data;
+
+    if (!doc.HasMember("statuses") || !doc["statuses"].IsArray()) {
+        return data;
+    }
+
+    const Value& statuses = doc["statuses"];
+    data.statuses.reserve(statuses.Size());
+
+    for (SizeType i = 0; i < statuses.Size(); i++) {
+        const Value& status_json = statuses[i];
+        Status status;
+
+        // Parse status fields
+        if (status_json.HasMember("created_at") && status_json["created_at"].IsString())
+            status.created_at = status_json["created_at"].GetString();
+        if (status_json.HasMember("id") && status_json["id"].IsUint64())
+            status.id = status_json["id"].GetUint64();
+        if (status_json.HasMember("text") && status_json["text"].IsString())
+            status.text = status_json["text"].GetString();
+        if (status_json.HasMember("retweet_count") && status_json["retweet_count"].IsUint64())
+            status.retweet_count = status_json["retweet_count"].GetUint64();
+        if (status_json.HasMember("favorite_count") && status_json["favorite_count"].IsUint64())
+            status.favorite_count = status_json["favorite_count"].GetUint64();
+
+        // Parse user
+        if (status_json.HasMember("user") && status_json["user"].IsObject()) {
+            const Value& user_json = status_json["user"];
+            User user;
+
+            if (user_json.HasMember("id") && user_json["id"].IsUint64())
+                user.id = user_json["id"].GetUint64();
+            if (user_json.HasMember("name") && user_json["name"].IsString())
+                user.name = user_json["name"].GetString();
+            if (user_json.HasMember("screen_name") && user_json["screen_name"].IsString())
+                user.screen_name = user_json["screen_name"].GetString();
+            if (user_json.HasMember("location") && user_json["location"].IsString())
+                user.location = user_json["location"].GetString();
+            if (user_json.HasMember("description") && user_json["description"].IsString())
+                user.description = user_json["description"].GetString();
+            if (user_json.HasMember("verified") && user_json["verified"].IsBool())
+                user.verified = user_json["verified"].GetBool();
+            if (user_json.HasMember("followers_count") && user_json["followers_count"].IsUint64())
+                user.followers_count = user_json["followers_count"].GetUint64();
+            if (user_json.HasMember("friends_count") && user_json["friends_count"].IsUint64())
+                user.friends_count = user_json["friends_count"].GetUint64();
+            if (user_json.HasMember("statuses_count") && user_json["statuses_count"].IsUint64())
+                user.statuses_count = user_json["statuses_count"].GetUint64();
+
+            status.user = user;
+        }
+
+        data.statuses.push_back(status);
+    }
+
+    return data;
+}
+
+// RapidJSON serialization for simplified Twitter data
+std::string rapidjson_serialize(const TwitterData& data) {
+    Document doc;
+    doc.SetObject();
+    Document::AllocatorType& allocator = doc.GetAllocator();
+
+    Value statuses_array(kArrayType);
+
+    for (const auto& status : data.statuses) {
+        Value status_obj(kObjectType);
+
+        Value created_at;
+        created_at.SetString(status.created_at.c_str(), allocator);
+        status_obj.AddMember("created_at", created_at, allocator);
+
+        status_obj.AddMember("id", status.id, allocator);
+
+        Value text;
+        text.SetString(status.text.c_str(), allocator);
+        status_obj.AddMember("text", text, allocator);
+
+        // Add user
+        Value user_obj(kObjectType);
+        user_obj.AddMember("id", status.user.id, allocator);
+
+        Value name;
+        name.SetString(status.user.name.c_str(), allocator);
+        user_obj.AddMember("name", name, allocator);
+
+        Value screen_name;
+        screen_name.SetString(status.user.screen_name.c_str(), allocator);
+        user_obj.AddMember("screen_name", screen_name, allocator);
+
+        Value location;
+        location.SetString(status.user.location.c_str(), allocator);
+        user_obj.AddMember("location", location, allocator);
+
+        Value description;
+        description.SetString(status.user.description.c_str(), allocator);
+        user_obj.AddMember("description", description, allocator);
+
+        user_obj.AddMember("verified", status.user.verified, allocator);
+        user_obj.AddMember("followers_count", status.user.followers_count, allocator);
+        user_obj.AddMember("friends_count", status.user.friends_count, allocator);
+        user_obj.AddMember("statuses_count", status.user.statuses_count, allocator);
+
+        status_obj.AddMember("user", user_obj, allocator);
+
+        status_obj.AddMember("retweet_count", status.retweet_count, allocator);
+        status_obj.AddMember("favorite_count", status.favorite_count, allocator);
+
+        statuses_array.PushBack(status_obj, allocator);
+    }
+
+    doc.AddMember("statuses", statuses_array, allocator);
+
+    StringBuffer buffer;
+    Writer<StringBuffer> writer(buffer);
+    doc.Accept(writer);
+
+    return buffer.GetString();
+}
+
+#endif // RAPIDJSON_TWITTER_DATA_H

benchmark/static_reflect/twitter_benchmark/twitter_data.h

@@ -4,68 +4,31 @@
 #include <string>
 #include <vector>
 
+// Simplified Twitter structures for benchmarking
+
 struct User {
-  int64_t id;
-  std::string id_str;
+  uint64_t id;
   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;
+  uint64_t followers_count;
+  uint64_t friends_count;
+  uint64_t statuses_count;
 };
 
 struct Status {
   std::string created_at;
-  int64_t id;
+  uint64_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;
+  uint64_t retweet_count;
+  uint64_t favorite_count;
 };
 
 struct TwitterData {
   std::vector<Status> statuses;
-  bool operator==(const TwitterData &other) const = default;
 };
 
-#endif
+#endif // TWITTER_DATA_H

benchmark/static_reflect/twitter_benchmark/yyjson_twitter_data.h

@@ -0,0 +1,145 @@
+#ifndef YYJSON_TWITTER_DATA_H
+#define YYJSON_TWITTER_DATA_H
+
+#include "twitter_data.h"
+#include <yyjson.h>
+#include <string>
+#include <stdexcept>
+
+// yyjson deserialization for simplified Twitter data
+TwitterData yyjson_deserialize(const std::string &json_str) {
+    TwitterData data;
+
+    yyjson_doc *doc = yyjson_read(json_str.c_str(), json_str.size(), 0);
+    if (!doc) {
+        throw std::runtime_error("yyjson parse error");
+    }
+
+    yyjson_val *root = yyjson_doc_get_root(doc);
+    if (!root) {
+        yyjson_doc_free(doc);
+        return data;
+    }
+
+    // Get statuses array
+    yyjson_val *statuses_val = yyjson_obj_get(root, "statuses");
+    if (!statuses_val || !yyjson_is_arr(statuses_val)) {
+        yyjson_doc_free(doc);
+        return data;
+    }
+
+    size_t idx, max;
+    yyjson_val *status_val;
+    yyjson_arr_foreach(statuses_val, idx, max, status_val) {
+        Status status;
+
+        // Parse status fields
+        yyjson_val *val;
+
+        val = yyjson_obj_get(status_val, "created_at");
+        if (val && yyjson_is_str(val)) status.created_at = yyjson_get_str(val);
+
+        val = yyjson_obj_get(status_val, "id");
+        if (val && yyjson_is_uint(val)) status.id = yyjson_get_uint(val);
+
+        val = yyjson_obj_get(status_val, "text");
+        if (val && yyjson_is_str(val)) status.text = yyjson_get_str(val);
+
+        val = yyjson_obj_get(status_val, "retweet_count");
+        if (val && yyjson_is_uint(val)) status.retweet_count = yyjson_get_uint(val);
+
+        val = yyjson_obj_get(status_val, "favorite_count");
+        if (val && yyjson_is_uint(val)) status.favorite_count = yyjson_get_uint(val);
+
+        // Parse user
+        yyjson_val *user_val = yyjson_obj_get(status_val, "user");
+        if (user_val && yyjson_is_obj(user_val)) {
+            User user;
+
+            val = yyjson_obj_get(user_val, "id");
+            if (val && yyjson_is_uint(val)) user.id = yyjson_get_uint(val);
+
+            val = yyjson_obj_get(user_val, "name");
+            if (val && yyjson_is_str(val)) user.name = yyjson_get_str(val);
+
+            val = yyjson_obj_get(user_val, "screen_name");
+            if (val && yyjson_is_str(val)) user.screen_name = yyjson_get_str(val);
+
+            val = yyjson_obj_get(user_val, "location");
+            if (val && yyjson_is_str(val)) user.location = yyjson_get_str(val);
+
+            val = yyjson_obj_get(user_val, "description");
+            if (val && yyjson_is_str(val)) user.description = yyjson_get_str(val);
+
+            val = yyjson_obj_get(user_val, "verified");
+            if (val && yyjson_is_bool(val)) user.verified = yyjson_get_bool(val);
+
+            val = yyjson_obj_get(user_val, "followers_count");
+            if (val && yyjson_is_uint(val)) user.followers_count = yyjson_get_uint(val);
+
+            val = yyjson_obj_get(user_val, "friends_count");
+            if (val && yyjson_is_uint(val)) user.friends_count = yyjson_get_uint(val);
+
+            val = yyjson_obj_get(user_val, "statuses_count");
+            if (val && yyjson_is_uint(val)) user.statuses_count = yyjson_get_uint(val);
+
+            status.user = user;
+        }
+
+        data.statuses.push_back(status);
+    }
+
+    yyjson_doc_free(doc);
+    return data;
+}
+
+// yyjson serialization for simplified Twitter data
+std::string yyjson_serialize(const TwitterData &data) {
+    yyjson_mut_doc *doc = yyjson_mut_doc_new(NULL);
+    yyjson_mut_val *root = yyjson_mut_obj(doc);
+    yyjson_mut_doc_set_root(doc, root);
+
+    // Create statuses array
+    yyjson_mut_val *statuses_array = yyjson_mut_arr(doc);
+
+    for (const auto& status : data.statuses) {
+        yyjson_mut_val *status_obj = yyjson_mut_obj(doc);
+
+        // Add status fields
+        yyjson_mut_obj_add_str(doc, status_obj, "created_at", status.created_at.c_str());
+        yyjson_mut_obj_add_uint(doc, status_obj, "id", status.id);
+        yyjson_mut_obj_add_str(doc, status_obj, "text", status.text.c_str());
+
+        // User object
+        yyjson_mut_val *user_obj = yyjson_mut_obj(doc);
+        yyjson_mut_obj_add_uint(doc, user_obj, "id", status.user.id);
+        yyjson_mut_obj_add_str(doc, user_obj, "name", status.user.name.c_str());
+        yyjson_mut_obj_add_str(doc, user_obj, "screen_name", status.user.screen_name.c_str());
+        yyjson_mut_obj_add_str(doc, user_obj, "location", status.user.location.c_str());
+        yyjson_mut_obj_add_str(doc, user_obj, "description", status.user.description.c_str());
+        yyjson_mut_obj_add_bool(doc, user_obj, "verified", status.user.verified);
+        yyjson_mut_obj_add_uint(doc, user_obj, "followers_count", status.user.followers_count);
+        yyjson_mut_obj_add_uint(doc, user_obj, "friends_count", status.user.friends_count);
+        yyjson_mut_obj_add_uint(doc, user_obj, "statuses_count", status.user.statuses_count);
+        yyjson_mut_obj_add_val(doc, status_obj, "user", user_obj);
+
+        // Other fields
+        yyjson_mut_obj_add_uint(doc, status_obj, "retweet_count", status.retweet_count);
+        yyjson_mut_obj_add_uint(doc, status_obj, "favorite_count", status.favorite_count);
+
+        yyjson_mut_arr_append(statuses_array, status_obj);
+    }
+
+    // Add statuses array to root
+    yyjson_mut_obj_add_val(doc, root, "statuses", statuses_array);
+
+    // Write to string
+    char *json_output = yyjson_mut_write(doc, 0, NULL);
+    std::string result(json_output);
+    free(json_output);
+    yyjson_mut_doc_free(doc);
+
+    return result;
+}
+
+#endif // YYJSON_TWITTER_DATA_H

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)

doc/basics.md

@@ -1,6 +1,7 @@
 The Basics
 ==========
 
+
 An overview of what you need to know to use simdjson to parse JSON documents, 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).
@@ -21,11 +22,13 @@ separate document](https://github.com/simdjson/simdjson/blob/master/doc/builder.
   * [1. Specialize `simdjson::ondemand::value::get` to get custom types (pre-C++20)](#1-specialize-simdjsonondemandvalueget-to-get-custom-types-pre-c20)
   * [2. Use `tag_invoke` for custom types (C++20)](#2-use-tag_invoke-for-custom-types-c20)
   * [3. Using static reflection (C++26)](#3-using-static-reflection-c26)
+    + [Special cases](#special-cases)
   * [The simdjson::from shortcut (experimental, C++20)](#the-simdjsonfrom-shortcut-experimental-c20)
 - [Minifying JSON strings without parsing](#minifying-json-strings-without-parsing)
 - [UTF-8 validation (alone)](#utf-8-validation-alone)
 - [JSON Pointer](#json-pointer)
 - [JSONPath](#jsonpath)
+- [Compile-Time JSONPath and JSON Pointer (C++26 Reflection)](#compile-time-jsonpath-and-json-pointer-c26-reflection)
 - [Error handling](#error-handling)
   * [Error handling examples without exceptions](#error-handling-examples-without-exceptions)
   * [Disabling exceptions](#disabling-exceptions)
@@ -66,7 +69,7 @@ Including simdjson
 To include simdjson, copy [simdjson.h](/singleheader/simdjson.h) and [simdjson.cpp](/singleheader/simdjson.cpp)
 into your project. Then include it in your project with:
 
-```c++
+```cpp
 #include "simdjson.h"
 using namespace simdjson; // optional
 ```
@@ -166,25 +169,30 @@ For efficiency reasons, simdjson requires a string with a few bytes (`simdjson::
 at the end, these bytes may be read but their content does not affect the parsing. In practice,
 it means that the JSON inputs should be stored in a memory region with `simdjson::SIMDJSON_PADDING`
 extra bytes at the end. You do not have to set these bytes to specific values though you may
-want to if you want to avoid runtime warnings with some sanitizers. Advanced users may want to
-read the section Free Padding in [our performance notes](performance.md).
+want to if you want to avoid runtime warnings with some sanitizers. We expect the user
+of the library to load the data (from disk or from the network) into a padded buffer. To make
+this easy, we provide the `padded_string::load` function which loads files from disk in a padded buffer.
+[You can similarly fetch a file from a URL to a padded string](https://github.com/simdjson/curltostring) using our `simdjson::padded_string_builder`. Advanced users may want to read the section Free Padding in [our performance notes](performance.md).
 
 The simdjson library offers a tree-like [API](https://en.wikipedia.org/wiki/API), which you can
 access by creating a `ondemand::parser` and calling the `iterate()` method. The iterate method
 quickly indexes the input string and may detect some errors. The following example illustrates
 how to get started with an input JSON file (`"twitter.json"`):
 
-```c++
+```cpp
 ondemand::parser parser;
 auto json = padded_string::load("twitter.json"); // load JSON file 'twitter.json'.
 ondemand::document doc = parser.iterate(json); // position a pointer at the beginning of the JSON data
 ```
 
+(Windows users compiling with C++17 or better may use `wchar_t` strings to support non-ASCII
+filenames: `padded_string::load(L"twitter.json")`.)
+
 If you prefer not to create your own `ondemand::parser` instance, you can access
 a thread-local version by calling `ondemand::parser.get_parser()`.
 
 
-```c++
+```cpp
 ondemand::document doc = ondemand::parser.get_parser().iterate(json);
 ```
 
@@ -194,7 +202,7 @@ document per thread at any one time.
 
 You can also create a padded string---and call `iterate()`:
 
-```c++
+```cpp
 ondemand::parser parser;
 auto json = "[1,2,3]"_padded; // The _padded suffix creates a simdjson::padded_string instance
 ondemand::document doc = parser.iterate(json); // parse a string
@@ -202,7 +210,7 @@ ondemand::document doc = parser.iterate(json); // parse a string
 
 If you have a buffer of your own with enough padding already (SIMDJSON_PADDING extra bytes allocated), you can use `padded_string_view` to pass it in:
 
-```c++
+```cpp
 ondemand::parser parser;
 char json[3+SIMDJSON_PADDING];
 strcpy(json, "[1]");
@@ -214,14 +222,14 @@ reference is non-const, it will allocate padding as needed.
 
 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
 ```
@@ -229,7 +237,7 @@ simdjson::padded_string my_padded_data(data); // copies to a padded buffer
 You can then parse the JSON data from the `simdjson::padded_string` instance:
 
 
-```c++
+```cpp
 ondemand::document doc = parser.iterate(my_padded_data);
 ```
 
@@ -241,7 +249,7 @@ 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:
 
-```c++
+```cpp
 std::string json = "[1]";
 ondemand::document doc = parser.iterate(simdjson::pad(json));
 ```
@@ -263,6 +271,21 @@ Further, they may use the AreFileApisANSI function to determine whether
 the filename is interpreted using the ANSI or the system default OEM
 codepage, and they may call SetFileApisToOEM accordingly.
 
+
+**Advanced feature:**
+On non-Windows systems, you can use memory-file mapping to create a `simdjson::padded_string_view`
+from a file on disk.
+
+```cpp
+// If the macro _WIN32 is defined, this will not work since we do not support memory-file mapping
+// under Windows at this time.
+simdjson::padded_memory_map map(myfilename);
+if (!map.is_valid()) { /* handle error */ }
+simdjson::padded_string_view view = map.view(); // view is usable while padded_memory_map is in scope
+ondemand::document doc = parser.iterate(view); // parse the JSON
+```
+
+
 Documents are iterators
 -----------------------
 
@@ -348,7 +371,13 @@ the  macro `SIMDJSON_DEVELOPMENT_CHECKS` to 1 prior to including
 the `simdjson.h` header to enable these additional checks: just make sure you remove the
 definition once your code has been tested. When `SIMDJSON_DEVELOPMENT_CHECKS` is set to 1, the
 simdjson library runs additional (expensive) tests on your code to help ensure that you are
-using the library in a safe manner.
+using the library in a safe manner. We add asserts which may halt your program, helping
+you find the bad programming pattern.
+
+When `SIMDJSON_DEVELOPMENT_CHECKS`, some of our data structures contain extra data for
+tracking explicitly potential programming mistakes. Thus you should not relying on the
+size (`sizeof`) of our data structures to be constant: they may change depending on the
+compiler settings.
 
 Once your code has been tested, you can then run it in
 Release mode: under Visual Studio, it means having the `_DEBUG` macro undefined, and, for other
@@ -360,6 +389,10 @@ builds to disable additional runtime testing and get the best performance. We
 disable these checks on a best-effort basis but the C++ standard does not provide
 a direct way to check for a release build.
 
+
+Warnign: Mixing debug and release simdjson code is unsafe: you either build all your code
+using simdjson in release mode or all of it in debug mode.
+
 Using the parsed JSON
 ---------------------
 
@@ -431,8 +464,8 @@ support for users who avoid exceptions. See [the simdjson error handling documen
 
   If you know the type of the value, you can cast it right there, too! `for (double value : array) { ... }`.
 
-  You may also use explicit iterators: `for(auto i = array.begin(); i != array.end(); i++) {}`. You can check that an array is empty with the condition `auto i = array.begin(); if (i == array.end()) {...}`.
-* **Object Iteration:** You can iterate through an object's fields, as well: `for (auto field : object) { ... }`. You may also use explicit iterators : `for(auto i = object.begin(); i != object.end(); i++) { auto field = *i; .... }`. You can check that an object is empty with the condition `auto i = object.begin(); if (i == object.end()) {...}`.
+  You may also use explicit iterators: `for(auto i = array.begin(); i != array.end(); i++) {}`. You can check that an array is empty with the condition `auto i = array.begin(); if (i == array.end()) {...}`. You should derefence (`*i`) an iterator at most once before incrementing it (`i++`), when compiling in debug mode with development checks, we add asserts to help you identify such a mistake.
+* **Object Iteration:** You can iterate through an object's fields, as well: `for (auto field : object) { ... }`.
   - `field.unescaped_key()` will get you the unescaped key string as a `std::string_view` instance. E.g., the JSON string `"\u00e1"` becomes the Unicode string `á`. Optionally,  you pass `true` as a parameter to the `unescaped_key` method if you want invalid escape sequences to be replaced by a default replacement character (e.g., `\ud800\ud801\ud811`): otherwise bad escape sequences lead to an immediate error.
   - `field.escaped_key()` will get you the key string as  as a `std::string_view` instance, but unlike `unescaped_key()`, the key is not processed, so no unescaping is done. E.g., the JSON string `"\u00e1"` becomes the Unicode string `\u00e1`. We expect that `escaped_key()` is faster than `field.unescaped_key()`.
   - `field.value()` will get you the value, which you can then use all these other methods on.
@@ -445,14 +478,18 @@ support for users who avoid exceptions. See [the simdjson error handling documen
 
   When you are iterating through an object, you are advancing through its keys and values. You should not also access the object or other objects. E.g. within a loop over `myobject`, you should not be accessing `myobject`. The following is an anti-pattern: `for(auto value: myobject) {myobject["mykey"]}`.
 
+  We discourage using the object iterators explicitly: `for(auto i = object.begin(); i != object.end(); i++) { auto field = *i; .... }`. In addition to the usual requirement to check against `end()` prior to dereferencing, you must also always dereference the pointer (`*it`) exactly once before you increment it (`it++`). You must also only deference the iterator once (never more than once). When compiling in
+  debug mode with development checks, we add asserts to help check whether you correctly
+  dereferenced the pointer before incrementing it.
+
   You should never reset an object as you are iterating through it. The following is an anti-pattern: `for(auto value: myobject) {myobject.reset()}`.
-* **Array Index:** Because it is forward-only, you cannot look up an array element by index by index. Instead,
+* **Array Index:** Because it is forward-only, you cannot look up an array element by index. Instead,
   you should iterate through the array and keep an index yourself. Exceptionally, if need a single value
   out of the array, you may use an array access (e.g., `array[1]`). You should never reset an array as you are iterating through it. The following is an anti-pattern: `for(auto value: myarray) {myarray.reset()}`.
 * **Field Access:** To get the value of the "foo" field in an object, use `object["foo"]`. This will
   scan through the object looking for the field with the matching string, doing a character-by-character
-  comparison. It may generate the error `simdjson::NO_SUCH_FIELD` if there is no such key in the object, it may throw an exception (see [Error handling](#error-handling)). For efficiency reason, you should avoid looking up the same field repeatedly: e.g., do
-  not do `object["foo"]` followed by `object["foo"]` with the same `object` instance. Generally, you should not mix and match iterating through an object (`for(auto field : object) {...}`) and key accesses (`object["foo"]`): if you need to iterate through an object after a key access, you need to call `reset()` on the object. Whenever you call `reset()`, you need to keep in mind that though you can iterate over the array repeatedly, values should be consumed only once (e.g., repeatedly calling `unescaped_key()` on the same  key is forbidden). Keep in mind that On-Demand does not buffer or save the result of the parsing: if you repeatedly access `object["foo"]`, then it must repeatedly seek the key and parse the content. The library does not provide a distinct function to check if a key is present, instead we recommend you attempt to access the key: e.g., by doing `ondemand::value val{}; if (!object["foo"].get(val)) {...}`, you have that `val` contains the requested value inside the if clause.  It is your responsibility as a user to temporarily keep a reference to the value (`auto v = object["foo"]`), or to consume the content and store it in your own data structures. If you consume an
+  comparison. It may generate the error `simdjson::NO_SUCH_FIELD` if there is no such key in the object, it may throw an exception (see [Error handling](#error-handling)). The returned value is only valid so long as you do not access another field: normally, you should therefore grab the value right after accessing a key (i.e., convert it to number, string, object, array...). For efficiency reason, you should avoid looking up the same field repeatedly: e.g., do
+  not do `object["foo"]` followed by `object["foo"]` with the same `object` instance. Generally, you should not mix and match iterating through an object (`for(auto field : object) {...}`) and key accesses (`object["foo"]`): if you need to iterate through an object after a key access, you need to call `reset()` on the object. Whenever you call `reset()`, you need to keep in mind that though you can iterate over the array repeatedly, values should be consumedonly once (e.g., repeatedly calling `unescaped_key()` on the same  key is forbidden). Keep in mind that On-Demand does not buffer or save the result of the parsing: if you repeatedly access `object["foo"]`, then it must repeatedly seek the key and parse the content. The library does not provide a distinct function to check if a key is present, instead we recommend you attempt to access the key: e.g., by doing `ondemand::value val{}; if (!object["foo"].get(val)) {...}`, you have that `val` contains the requested value inside the if clause.  It is your responsibility as a user to temporarily keep a reference to the value (`auto v = object["foo"]`), or to consume the content and store it in your own data structures. If you consume an
   object twice: `std::string_view(object["foo"]` followed by `std::string_view(object["foo"]` then your code
   is in error. Furthermore, you can only consume one field at a time, on the same object. The
   value instance you get from  `content["bids"]` becomes invalid when you call `content["asks"]`.
@@ -474,8 +511,8 @@ support for users who avoid exceptions. See [the simdjson error handling documen
   > which returns a `std::string_view` instance pointing directly in the document, like `key()`, although,
   > unlike `key()`, it has to determine the location of the final quote character.
   >
-  > ```c++
-  > auto json = R"({"k\u0065y": 1})"_padded;
+  > ```cpp
+  > auto json = R"({"k\u0065y": 1})"_padded; // R"( ... )" is a C++ raw string literal.
   > ondemand::parser parser;
   > auto doc = parser.iterate(json);
   > ondemand::object object = doc.get_object();
@@ -498,9 +535,9 @@ support for users who avoid exceptions. See [the simdjson error handling documen
   > This will only look forward, and will fail to find fields in the wrong order: for example, this
   > will fail:
   >
-  > ```c++
+  > ```cpp
   > ondemand::parser parser;
-  > auto json = R"(  { "x": 1, "y": 2 }  )"_padded;
+  > auto json = R"(  { "x": 1, "y": 2 }  )"_padded; //  R"( ... )" is a C++ raw string literal.
   > auto doc = parser.iterate(json);
   > double y = doc.find_field("y"); // The cursor is now after the 2 (at })
   > double x = doc.find_field("x"); // This fails, because there are no more fields after "y"
@@ -508,7 +545,7 @@ support for users who avoid exceptions. See [the simdjson error handling documen
   >
   > By contrast, using the default (order-insensitive) lookup succeeds:
   >
-  > ```c++
+  > ```cpp
   > ondemand::parser parser;
   > auto json = R"(  { "x": 1, "y": 2 }  )"_padded;
   > auto doc = parser.iterate(json);
@@ -516,20 +553,20 @@ support for users who avoid exceptions. See [the simdjson error handling documen
   > double x = doc["x"]; // Success: [] loops back around to find "x"
   > ```
 * **Output to strings:** Given a document, a value, an array or an object in a JSON document, you can output a JSON string version suitable to be parsed again as JSON content: `simdjson::to_json_string(element)`. A call to `to_json_string` consumes fully the element: if you apply it on a document, the internal pointer is advanced to the end of the document. The `simdjson::to_json_string` does not allocate memory. The `to_json_string` function should not be confused with retrieving the value of a string instance which are escaped and represented using a lightweight `std::string_view` instance pointing at an internal string buffer inside the parser instance. To illustrate, the first of the following two code segments will print the unescaped string `"test"` complete with the quote whereas the second one will print the escaped content of the string (without the quotes).
-  > ```C++
+  > ```cpp
   > // serialize a JSON to an escaped std::string instance so that it can be parsed again as JSON
   > auto silly_json = R"( { "test": "result"  }  )"_padded;
   > ondemand::document doc = parser.iterate(silly_json);
   > std::cout << simdjson::to_json_string(doc["test"]) << std::endl; // Requires simdjson 1.0 or better
-  >````
-  > ```C++
+  > ```
+  > ```cpp
   > // retrieves an unescaped string value as a string_view instance
   > auto silly_json = R"( { "test": "result"  }  )"_padded;
   > ondemand::document doc = parser.iterate(silly_json);
   > std::cout << std::string_view(doc["test"]) << std::endl;
-  >````
+  > ```
   You can use `to_json_string` to efficiently extract components of a JSON document to reconstruct a new JSON document, as in 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 ] },
@@ -556,13 +593,13 @@ support for users who avoid exceptions. See [the simdjson error handling documen
   > oss << "]";
   > auto json_string = oss.str();
   > // json_string == "[[ 40.1, 39.9, 37.7, 40.4 ],[ 30.1, 31.0, 28.6, 28.7 ]]"
-  >````
+  > ```
 * **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`, `ondemand::object` and `ondemand::array`) and pass it by reference
   to `get()` which gives you back an error code: e.g.,
 
-  ```c++
+  ```cpp
   auto abstract_json = R"(
     { "str" : { "123" : {"abc" : 3.14 } } }
   )"_padded;
@@ -583,7 +620,7 @@ support for users who avoid exceptions. See [the simdjson error handling documen
   whole array. You should only call `count_elements` as a last resort as it may
   require scanning the document twice or more. You should never use the `count_elements` as part of an attempt to iterate through the array: use a `for` loop to iterate through arrays. In the spirit of On-Demand, the `count_elements` function does not validate the values in the array: they are validated when they are consumed. You may use it as follows if your document is itself an array:
 
-  ```C++
+  ```cpp
   auto cars_json = R"( [ 40.1, 39.9, 37.7, 40.4 ] )"_padded;
   auto doc = parser.iterate(cars_json);
   size_t count = doc.count_elements(); // requires simdjson 1.0 or better
@@ -611,7 +648,7 @@ support for users who avoid exceptions. See [the simdjson error handling documen
   whole objects. You should only call `count_fields` as a last resort as it may
   require scanning the document twice or more.  You may use it as follows if your document is itself an object:
 
-  ```C++
+  ```cpp
   ondemand::parser parser;
   auto json = R"( { "test":{ "val1":1, "val2":2 } }   )"_padded;
   auto doc = parser.iterate(json);
@@ -642,7 +679,7 @@ support for users who avoid exceptions. See [the simdjson error handling documen
   You must still validate and consume the values (e.g., call `is_null()`) after calling `type()`.
    You may also access [the raw JSON string](#general-direct-access-to-the-raw-json-string).
   For example, the following is a quick and dirty recursive function that verbosely prints the JSON document as JSON. This example also illustrates lifecycle requirements: the `document` instance holds the iterator. The document must remain in scope while you are accessing instances of `value`, `object` and `array`.
-  ```c++
+  ```cpp
   void recursive_print_json(ondemand::value element) {
     bool add_comma;
     switch (element.type()) {
@@ -724,7 +761,7 @@ Let us review these concepts with some additional examples. For simplicity, we o
 
 The first example illustrates how we can chain operations. In this instance, we repeatedly select keys using the bracket operator (`doc["str"]`) and then finally request a number (using `get_double()`). It is safe to write code in this manner: if any step causes an error, the error status propagates and an exception is thrown at the end. You do not need to constantly check for errors.
 
-```C++
+```cpp
 auto abstract_json = R"(
   { "str" : { "123" : {"abc" : 3.14 } } }
 )"_padded;
@@ -738,7 +775,7 @@ an array of objects. We iterate through the objects using a for-loop. Within eac
 the bracket operator (e.g., `car["make"]`) to select values. We also show how we can iterate through an
 array, corresponding to the key `tire_pressure`,  that is contained inside each object.
 
-```c++
+```cpp
 ondemand::parser parser;
 auto cars_json = R"( [
   { "make": "Toyota", "model": "Camry",  "year": 2018, "tire_pressure": [ 40.1, 39.9, 37.7, 40.4 ] },
@@ -768,7 +805,7 @@ for (ondemand::object car : parser.iterate(cars_json)) {
 The previous example had an array of objects, but we can use essentially the same
 approach with an object of objects.
 
-```c++
+```cpp
 ondemand::parser parser;
 auto cars_json = R"( {
   "identifier1":{ "make": "Toyota", "model": "Camry",  "year": 2018, "tire_pressure": [ 40.1, 39.9, 37.7, 40.4 ] },
@@ -803,7 +840,7 @@ for (ondemand::field key_car : doc.get_object()) {
 
 The following example illustrates how you may also iterate through object values, effectively visiting all key-value pairs in the object.
 
-```C++
+```cpp
 #include <iostream>
 #include "simdjson.h"
 using namespace std;
@@ -852,7 +889,7 @@ The C++26 approach is even simpler.
 
 Suppose you have your own types, such as a `Car` struct:
 
-```C++
+```cpp
 struct Car {
   std::string make;
   std::string model;
@@ -864,7 +901,7 @@ struct Car {
 You might want to write code that automatically parses the JSON content to your custom
 type:
 
-```C++
+```cpp
   padded_string json = R"( [ { "make": "Toyota", "model": "Camry",  "year": 2018,
        "tire_pressure": [ 40.1, 39.9 ] },
   { "make": "Kia",    "model": "Soul",   "year": 2012,
@@ -889,7 +926,7 @@ is automatically provided by simdjson if C++20 (and concepts) are available.
 See [Use `tag_invoke` for custom types](#2-use-tag_invoke-for-custom-types-c20) if you have
 C++20 support.
 
-```c++
+```cpp
 #if !SIMDJSON_SUPPORTS_CONCEPTS
 // The code is unnecessary with C++20:
 template <>
@@ -912,7 +949,7 @@ simdjson::ondemand::value::get() noexcept {
 
 We may then provide support for our `Car` struct:
 
-```C++
+```cpp
 template <>
 simdjson_inline simdjson_result<Car> simdjson::ondemand::value::get() noexcept {
   ondemand::object obj;
@@ -929,7 +966,7 @@ simdjson_inline simdjson_result<Car> simdjson::ondemand::value::get() noexcept {
 
 And that is all that is needed! The following code is a complete example:
 
-```c++
+```cpp
 #include "simdjson.h"
 #include <iostream>
 #include <vector>
@@ -1000,7 +1037,7 @@ Observe that we require an explicit cast (`Car c(val)` instead of `for (Car c :
 
 If you prefer to avoid exceptions, you may modify the `main` function as follows:
 
-```c++
+```cpp
 int main(void) {
   padded_string json = R"( [ { "make": "Toyota", "model": "Camry",  "year": 2018,
        "tire_pressure": [ 40.1, 39.9 ] },
@@ -1030,7 +1067,7 @@ the `ondemand::document` type. In this instance, we must replace the function wi
 `simdjson_result<Car> simdjson::ondemand::document::get() &`. The following is a complete
 example:
 
-```C++
+```cpp
 #include "simdjson.h"
 #include <iostream>
 #include <vector>
@@ -1110,7 +1147,7 @@ The simdjson library takes advantage of C++20. An immediate benefit
 is that you can deserialize JSON data directly in standard containers
 and other standard value types:
 
-```C++
+```cpp
 simdjson::padded_string json = R"({"data" : [1,2,3,4]})"_padded;
 
 simdjson::ondemand::parser parser;
@@ -1120,7 +1157,7 @@ std::vector<uint8_t> array = d["data"].get<std::vector<uint8_t>>();
 
 Appending to an existing container is just as easy:
 
-```C++
+```cpp
 std::vector<uint32_t> array = {0, 0};
 
 simdjson::padded_string json = R"({"data" : [1,2,3,4]})"_padded;
@@ -1147,7 +1184,7 @@ to 1, otherwise it is set to 0.
 
 Consider a custom class `Car`:
 
-```C++
+```cpp
 struct Car {
   std::string make;
   std::string model;
@@ -1164,7 +1201,7 @@ You may support deserializing directly from a JSON value or document to your own
 by defining a single `tag_invoke` function:
 
 
-```C++
+```cpp
 namespace simdjson {
 // This tag_invoke MUST be inside simdjson namespace
 template <typename simdjson_value>
@@ -1279,7 +1316,7 @@ By default, we support a wide range of standard templates such as
 etc. They are handled automatically.
 
 E.g., you can recover an `std::unique_ptr<Car>` like so:
-```C++
+```cpp
 int main() {
   auto const json = R"( { "make": "Toyota", "model": "Camry",  "year": 2018,
        "tire_pressure": [ 40.1, 39.9 ] })"_padded;
@@ -1293,7 +1330,7 @@ int main() {
 
 You may also conditionally fill in `std::optional` values.
 
-```C++
+```cpp
   padded_string json =
       R"( { "car1": { "make": "Toyota", "model": "Camry",  "year": 2018,
        "tire_pressure": [ 40.1, 39.9 ] }
@@ -1312,7 +1349,7 @@ You can also deserialize to map-like types with keys that can be constructed
 from `std::string_view` instances:
 
 
-```C++
+```cpp
   padded_string json =
       R"( { "car1": { "make": "Toyota", "model": "Camry",  "year": 2018,
        "tire_pressure": [ 40.1, 39.9 ] }
@@ -1332,7 +1369,7 @@ Suppose for example that you want to construct an instance of `std::list<Car>`,
 you also want to filter out any car made by Toyota. You may provide your own
 `tag_invoke` function:
 
-```c++
+```cpp
 namespace simdjson {
 // suppose we want to filter out all Toyotas
 template <typename simdjson_value>
@@ -1377,7 +1414,7 @@ Then you can deserialize a type such as `Car` automatically:
 
 
 
-```C++
+```cpp
 struct Car {
   std::string make;
   std::string model;
@@ -1543,7 +1580,7 @@ Minifying JSON strings without parsing
 
 In some cases, you may have valid JSON strings that you do not wish to parse but that you wish to minify. That is, you wish to remove all unnecessary spaces. We have a fast function for this purpose (`simdjson::minify(const char * input, size_t length, const char * output, size_t& new_length)`). This function does not validate your content, and it does not parse it.  It is much faster than parsing the string and re-serializing it in minified form (`simdjson::minify(parser.parse())`). Usage is relatively simple. You must pass an input pointer with a length parameter, as well as an output pointer and an output length parameter (by reference). The output length parameter is not read, but written to. The output pointer should point to a valid memory region that is as large as the original string length. The input pointer and input length are read, but not written to.
 
-```C++
+```cpp
   // Starts with a valid JSON document as a string.
   // It does not have to be null-terminated.
   const char * some_string = "[ 1, 2, 3, 4] ";
@@ -1564,7 +1601,7 @@ UTF-8 validation (alone)
 
 The simdjson library has fast functions to validate UTF-8 strings. They are many times faster than most functions commonly found in libraries. You can use our fast functions, even if you do not care about JSON.
 
-```C++
+```cpp
   const char * some_string = "[ 1, 2, 3, 4] ";
   size_t length = std::strlen(some_string);
   bool is_ok = simdjson::validate_utf8(some_string, length);
@@ -1581,11 +1618,11 @@ 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. JSON Pointer is supported by both the [DOM approach](https://github.com/simdjson/simdjson/blob/master/doc/dom.md#json-pointer) as well as the On-Demand approach.
 
-**Note:** The On-Demand implementation of JSON Pointer relies on `find_field` which implies that it does not unescape keys when matching.
+**Note:** When matching keys, we do a byte-by-byte comparison. We do not unescape keys when matching.
 
 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 ] },
@@ -1603,7 +1640,7 @@ select the value. If your keys contain the characters '/' or '~', they must be e
 
 For multiple JSON Pointer queries on a document, one can call `at_pointer` multiple times.
 
-```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 ] },
@@ -1624,7 +1661,7 @@ In most instances, a JSON Pointer is an ASCII string and the keys in a JSON docu
 are ASCII strings. We support UTF-8 in JSON Pointer, but key values are matched exactly, without unescaping or Unicode normalization. We do a byte-by-byte comparison. The e acute character is
 considered distinct from its escaped version `\u00E9`. E.g.,
 
-```c++
+```cpp
 const padded_string json = "{\"\\u00E9\":123}"_padded;
 auto doc = parser.iterate(json);
 doc.at_pointer("/\\u00E9") == 123; // true
@@ -1633,7 +1670,7 @@ doc.at_pointer((const char*)u8"/\u00E9") // returns an error (NO_SUCH_FIELD)
 
 Note that `at_pointer` calls [`rewind`](#rewind) to reset the parser at the beginning of the document. Hence, it invalidates all previously parsed values, objects and arrays: make sure to consume the values between each call to  `at_pointer`. Consider the following example where one wants to store each object from the JSON into a vector of `struct car_type`:
 
-```c++
+```cpp
 struct car_type {
     std::string make;
     std::string model;
@@ -1676,7 +1713,7 @@ for (int i = 0; i < 3; i++) {
 
 Furthermore, `at_pointer` calls `rewind` at the beginning of the call (i.e. the document is not reset after `at_pointer`). Consider the following example,
 
-```c++
+```cpp
 auto json = R"( {
   "k0": 27,
   "k1": [13,26],
@@ -1696,7 +1733,7 @@ be represented as `value` instances. You can check that a document is a scalar w
 JSONPath
 ------------
 
-The simdjson library supports a subset of [JSONPath](https://datatracker.ietf.org/doc/html/draft-normington-jsonpath-00) 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.
+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.
 
 This implementation relies on `at_path()` converting its argument to JSON Pointer and then calling `at_pointer`, which makes use of
 [`rewind`](#rewind) to reset the parser at the beginning of the document. Hence, it invalidates all previously parsed values, objects
@@ -1704,7 +1741,7 @@ This implementation relies on `at_path()` converting its argument to JSON Pointe
 
 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 ] },
@@ -1717,7 +1754,7 @@ cout << cars.at_path("[0].tire_pressure[1]") << endl; // Prints 39.9
 
 A call to `at_path(json_path)` can result in any of the errors that are returned by the `at_pointer` method and if the conversion of `json_path` to JSON Pointer fails, it will lead to an `simdjson::INVALID_JSON_POINTER`error.
 
-```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 ] },
@@ -1734,7 +1771,7 @@ are ASCII strings. We support UTF-8 within a JSONPath expression, but key values
 matched exactly, without unescaping or Unicode normalization. We do a byte-by-byte comparison.
 The e acute character is considered distinct from its escaped version `\u00E9`. E.g.,
 
-```c++
+```cpp
 const padded_string json = "{\"\\u00E9\":123}"_padded;
 auto doc = parser.iterate(json);
 doc.at_path(".\\u00E9") == 123; // true
@@ -1744,7 +1781,7 @@ doc.at_path((const char*)u8".\u00E9") // returns an error (NO_SUCH_FIELD)
 
 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.,
 
-```c++
+```cpp
 auto json = R"( { "c" :{ "foo": { "a": [ 10, 20, 30 ] }}, "d": { "foo2": { "a": [ 10, 20, 30 ] }} , "e": 120 })"_padded;
 ondemand::parser parser;
 ondemand::document doc = parser.iterate(json);
@@ -1753,6 +1790,89 @@ int64_t x = obj.at_path("$.c.foo.a[1]"); // 20
 x = obj.at_path("$.d.foo2.a.2"); // 30
 ```
 
+## Using `at_path_with_wildcard` for JSONPath Queries (On-Demand)
+
+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;
+
+ondemand::parser parser;
+ondemand::document doc = parser.iterate(json_string);
+
+// Fetch all fields in the address object
+std::vector<ondemand::value> values;
+auto error = doc.at_path_with_wildcard("$.address.*").get(values);
+if (!error) {
+  for (auto value : values) {
+    std::string_view field;
+    if (value.get(field) == SUCCESS) {
+      std::cout << field << std::endl;
+    }
+  }
+}
+
+// Fetch all phone numbers
+error = doc.at_path_with_wildcard("$.phoneNumbers[*].numbers[*]").get(values);
+if (!error) {
+  for (auto value : values) {
+    std::string_view number;
+    if (value.get(number) == SUCCESS) {
+      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.
+
+## Compile-Time JSONPath and JSON Pointer (C++26 Reflection)
+
+The simdjson library provides **compile-time validated** JSONPath and JSON Pointer accessors when using C++26 Static Reflection. These accessors validate paths against struct definitions at compile time and generate optimized code with zero runtime overhead. In some cases, we find that it is much faster. Furthermore, it is safer in the sense that the expression
+is validated at compile-time.
+
+**Requirements:** C++26 compiler with P2996 reflection support and `-DSIMDJSON_STATIC_REFLECTION=ON` build flag.
+
+```cpp
+ondemand::parser parser;
+auto doc = parser.iterate(json);
+
+// Without validation - path parsed at compile time only
+std::string_view city;
+result = ondemand::json_path::at_path_compiled<".address.city">(doc);
+result.get(city);
+```
+
+We further provide type-validation so that you can check that the types are as you expect.
+
+**See [Compile-Time Accessors](compile_time_accessors.md) for complete documentation.**
+
 Error handling
 --------------
 
@@ -1761,7 +1881,7 @@ Error handling with exception and a single try/catch clause makes the code simpl
 The entire simdjson API is usable with and without exceptions. 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() without generating an exception, like so:
 
-```c++
+```cpp
 ondemand::document doc;
 auto error = parser.iterate(json).get(doc);
 if(error) { std::cerr << simdjson::error_message(error); exit(1); }
@@ -1798,7 +1918,7 @@ set of warnings: they can identify variables that are written to but never other
 Let us illustrate with an example where we try to access a number that is not valid (`3.14.1`).
 If we want to proceed without throwing and catching exceptions, we can do so as follows:
 
-```C++
+```cpp
 bool simple_error_example() {
     ondemand::parser parser;
     auto json = R"({"bad number":3.14.1 })"_padded;
@@ -1820,7 +1940,7 @@ Observe how we verify the error variable before accessing the retrieved number (
 
 The equivalent with exception handling might look as follows.
 
-```C++
+```cpp
   bool simple_error_example_except() {
     TEST_START();
     ondemand::parser parser;
@@ -1861,7 +1981,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"
 
@@ -1893,7 +2013,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"
 
@@ -1919,7 +2039,7 @@ to iterate through the values of an array. We deliberately forbid this usage to
 
 This is how the example in "Using the parsed JSON" could be written using only error code checking (without exceptions):
 
-```c++
+```cpp
 bool parse() {
   ondemand::parser parser;
   auto cars_json = R"( [
@@ -1976,7 +2096,7 @@ bool parse() {
 For safety, you should only use our ondemand instances (e.g., `ondemand::object`)
 after you have initialized them and checked that there is no error:
 
-```c++
+```cpp
     ondemand::object car; // invalid until the get() succeeds
     // the `car` instance should not use used before it is initialized
     error = car_value.get_object().get(car);
@@ -1989,7 +2109,7 @@ after you have initialized them and checked that there is no error:
 
 The following examples illustrates how to iterate through the content of an object without
 having to handle exceptions.
-```c++
+```cpp
   auto json = R"({"k\u0065y": 1})"_padded;
   ondemand::parser parser;
   ondemand::document doc;
@@ -2025,7 +2145,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
 simdjson::ondemand::document doc = parser.iterate(json); // Throws an exception if there was an error!
 ```
 
@@ -2035,7 +2155,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"
 
@@ -2052,7 +2172,7 @@ int main(void) {
 
 You can do handle errors gracefully as well...
 
-```C++
+```cpp
 #include <iostream>
 #include "simdjson.h"
 int main(void) {
@@ -2079,7 +2199,7 @@ When the input was a `padding_string` or another null-terminated source, then yo
 use the `const char *` pointer as a C string. As an example, consider the following
 example where we used the exception-free simdjson interface:
 
-```c++
+```cpp
 auto broken_json = R"( {"double": 13.06, false, "integer": -343} )"_padded;    // Missing key
 ondemand::parser parser;
 auto doc = parser.iterate(broken_json);
@@ -2099,7 +2219,7 @@ if (error) {
 
 You may also use `current_location()` with exceptions as follows:
 
-```c++
+```cpp
 auto broken_json = R"( {"double": 13.06, false, "integer": -343} )"_padded;
 ondemand::parser parser;
 ondemand::document doc = parser.iterate(broken_json);
@@ -2116,7 +2236,7 @@ had to go through a value without a key before (`false`), a `TAPE_ERROR` error i
 The pointer returned by the `current_location()` method then points at the location of the error. The `current_location()` may also be used when the error is triggered
 by a user action, even if the JSON input is valid. Consider the following example:
 
-```c++
+```cpp
 auto json = R"( [1,2,3] )"_padded;
 ondemand::parser parser;
 auto doc = parser.iterate(json);
@@ -2131,7 +2251,7 @@ if (error) {
 If the location is invalid (i.e. at the end of a document), the `current_location()`
 methods returns an `OUT_OF_BOUNDS` error. For example:
 
-```c++
+```cpp
 auto json = R"( [1,2,3] )"_padded;
 ondemand::parser parser;
 auto doc = parser.iterate(json);
@@ -2147,7 +2267,7 @@ then the document has more content.
 Finally, the `current_location()` method may also be used even when no exceptions/errors
 are thrown. This can be helpful for users that want to know the current state of iteration during parsing. For example:
 
-```c++
+```cpp
 auto json = R"( [[1,2,3], -23.4, {"key": "value"}, true] )"_padded;
 ondemand::parser parser;
 auto doc = parser.iterate(json);
@@ -2180,7 +2300,7 @@ content.
 
 Example 1.
 
-```C++
+```cpp
   auto json = R"([1, 2] foo ])"_padded;
   ondemand::parser parser;
   ondemand::document doc = parser.iterate(json);
@@ -2223,7 +2343,7 @@ that you have created so far (including unescaped strings).
 In the following example, we print on the screen the number of cars in the JSON input file
 before printout the data.
 
-```C++
+```cpp
   ondemand::parser parser;
   auto cars_json = R"( [
     { "make": "Toyota", "model": "Camry",  "year": 2018, "tire_pressure": [ 40.1, 39.9, 37.7, 40.4 ] },
@@ -2271,7 +2391,7 @@ individual document must be no larger than 4 GB.
 
 Here is an example:
 
-```c++
+```cpp
 auto json = R"({ "foo": 1 } { "foo": 2 } { "foo": 3 } )"_padded;
 ondemand::parser parser;
 ondemand::document_stream docs = parser.iterate_many(json);
@@ -2293,7 +2413,7 @@ The `iterate_many` function can also take an optional parameter `size_t batch_si
 
 The following toy examples illustrates how to get capacity errors. It is an artificial example since you should never use a `batch_size` of 50 bytes (it is far too small).
 
-```c++
+```cpp
 // We are going to set the capacity to 50 bytes which means that we cannot
 // loading a document longer than 50 bytes. The first few documents are small,
 // but the last one is large. We will get an error at the last document.
@@ -2353,7 +2473,7 @@ methods appropriately. In particular, a valid JSON number has no leading and no
 numbers (although you have access to the raw string with the `raw_json_token()` method,  see [General direct access to the raw JSON string](#general-direct-access-to-the-raw-json-string)
 ). As an example, suppose we have the following JSON text:
 
-```c++
+```cpp
 auto json =
 {
    "ticker":{
@@ -2387,7 +2507,7 @@ auto json =
 
 Now, suppose that a user wants to get the time stamp from the `timestampstr` key. One could do the following:
 
-```c++
+```cpp
 ondemand::parser parser;
 auto doc = parser.iterate(json);
 uint64_t time = doc.at_pointer("/timestampstr").get_uint64_in_string();
@@ -2396,7 +2516,7 @@ std::cout << time << std::endl;   // Prints 1399490941
 
 Another thing a user might want to do is extract the `markets` array and get the market name, price and volume. Here is one way to do so:
 
-```c++
+```cpp
 ondemand::parser parser;
 auto doc = parser.iterate(json);
 
@@ -2418,7 +2538,7 @@ Market: btce    Price: 432.89   Volume: 8561.06
 
 Finally, here is an example dealing with errors where the user wants to convert the string `"Infinity"`(`"change"` key) to a float with infinity value.
 
-```c++
+```cpp
 ondemand::parser parser;
 auto doc = parser.iterate(json);
 // Get "change"/"Infinity" key/value pair
@@ -2487,7 +2607,7 @@ The `get_number()` function is designed with performance in mind. When calling `
 
 
 Consider the following example:
-```C++
+```cpp
     ondemand::parser parser;
     padded_string docdata = R"([1.0, 3, 1, 3.1415,-13231232,9999999999999999999])"_padded;
     ondemand::document doc = parser.iterate(docdata);
@@ -2534,7 +2654,7 @@ unsigned integers. Calling `get_number_type()` on the values returns `ondemand::
 You can try to represent these big integers as 64-bit floating-point numbers, though you typically lose
 precision in the process (as illustrated in the example).
 
-```C++
+```cpp
   ondemand::parser parser;
   padded_string docdata = R"([-9223372036854775809, 18446744073709551617, 99999999999999999999999 ])"_padded;
   double dexpected[] = {-9223372036854775808.0, 18446744073709551616.0, 1e23};
@@ -2557,7 +2677,7 @@ This program might print:
 You may get access to the underlying string representing the big integer with
 `raw_json_token()` and you may parse the resulting number strings using your own parser.
 
-```c++
+```cpp
   ondemand::parser parser;
   padded_string docdata = R"([-9223372036854775809, 18446744073709551617, 99999999999999999999999 ])"_padded;
   ondemand::document doc = parser.iterate(docdata);
@@ -2596,7 +2716,7 @@ you should ensure that you have sufficient memory space: the total size of the s
 `simdjson::SIMDJSON_PADDING` bytes. The following example illustrates how we can unescape
 JSON string to a user-provided buffer:
 
-```C++
+```cpp
     auto json = R"( {"name": "Jack The Ripper \u0033"} )"_padded;
     // We create a buffer large enough to store all strings we need:
     std::unique_ptr<uint8_t[]> buffer(new uint8_t[json.size() + simdjson::SIMDJSON_PADDING]);
@@ -2620,7 +2740,7 @@ purpose. It provides a view on the key, including the starting quote character,
 and everything up to the next `:` character after the final quote character. E.g.,
 if the key is `"name"` then `key_raw_json_token()` returns a `std::string_view`  which
 begins with `"name"` and may containing trailing white-space characters.
-```C++
+```cpp
   auto json = R"( {"name" : "Jack The Ripper \u0033"} )"_padded;
   ondemand::parser parser;
   ondemand::document doc = parser.iterate(json);
@@ -2643,7 +2763,7 @@ The library makes this possible by providing a `raw_json_token` method which ret
 a `std::string_view` instance containing the value as a string which you may then
 parse as you see fit.
 
-```C++
+```cpp
 simdjson::ondemand::parser parser;
 simdjson::padded_string docdata =  R"({"value":12321323213213213213213213213211223})"_padded;
 simdjson::ondemand::document doc = parser.iterate(docdata);
@@ -2656,7 +2776,7 @@ The `raw_json_token` method even works when the JSON value is a string. In such
 will return the complete string with the quotes and with eventual escaped sequences as in the
 source document.
 
-```C++
+```cpp
 simdjson::ondemand::parser parser;
 simdjson::padded_string docdata =  R"({"value":"12321323213213213213213213213211223"})"_padded;
 simdjson::ondemand::document doc = parser.iterate(docdata);
@@ -2704,7 +2824,7 @@ If your value is an array or an object, `raw_json_token()` returns effectively a
 character (`[`) or (`}`) which is not very useful. For arrays and objects, we have another
 method called `raw_json()` which consumes (traverses) the array or the object.
 
-```C++
+```cpp
 simdjson::ondemand::parser parser;
 simdjson::padded_string docdata =  R"({"value":123})"_padded;
 simdjson::ondemand::document doc = parser.iterate(docdata);
@@ -2713,7 +2833,7 @@ string_view token = obj.raw_json(); // gives you `{"value":123}`
 ```
 
 
-```C++
+```cpp
 simdjson::ondemand::parser parser;
 simdjson::padded_string docdata =  R"([1,2,3])"_padded;
 simdjson::ondemand::document doc = parser.iterate(docdata);
@@ -2724,7 +2844,7 @@ string_view token = arr.raw_json(); // gives you `[1,2,3]`
 Because `raw_json()` consumes to object or the array, if you want to both have
 access to the raw string, and also use the array or object, you should call `reset()`.
 
-```C++
+```cpp
 simdjson::ondemand::parser parser;
 simdjson::padded_string docdata =  R"({"value":123})"_padded;
 simdjson::ondemand::document doc = parser.iterate(docdata);
@@ -2740,7 +2860,7 @@ value is an array or an object. Otherwise, it acts as `raw_json_token()`.
 It is useful if you do not care for the type of the value and just wants a
 string representation.
 
-```C++
+```cpp
   auto json = R"( [1,2,"fds", {"a":1}, [1,344]] )"_padded;
   ondemand::parser parser;
   ondemand::document doc = parser.iterate(json);
@@ -2751,7 +2871,7 @@ string representation.
   }
 ```
 
-```C++
+```cpp
   auto json = R"( {"key1":1,"key2":2,"key3":"fds", "key4":{"a":1}, "key5":[1,344]} )"_padded;
   ondemand::parser parser;
   ondemand::document doc = parser.iterate(json);
@@ -2799,7 +2919,7 @@ However, they are cases where you need to store a string result in a `std::strin
 instance. You can do so with a templated version of the `to_string()` method which takes as
 a parameter a reference to a `std::string`.
 
-```C++
+```cpp
   auto json = R"({
   "name": "Daniel",
   "age": 42
@@ -2813,7 +2933,7 @@ a parameter a reference to a `std::string`.
 
 The same routine can be written without exceptions handling:
 
-```C++
+```cpp
   std::string name;
   auto error = doc["name"].get_string(name);
   if (error) { /* handle error */ }
@@ -2826,7 +2946,7 @@ only consume a JSON string once.
 Because `get_string()` is a template that requires a type that can be assigned a `std::string`, you
 can use it with features such as `std::optional`:
 
-```C++
+```cpp
   auto json = R"({ "foo1": "3.1416" } )"_padded;
   ondemand::parser parser;
   ondemand::document doc = parser.iterate(json);
@@ -2907,7 +3027,7 @@ For simplicity, we do not include full error support: this code would throw exce
 
 * Example 1: ZuluBBox
 
-```C++
+```cpp
 struct ZuluBBox {
   double xmin;
   double ymin;
@@ -3011,7 +3131,7 @@ bool example() {
 
 * Example 2: Demos
 
-```C++
+```cpp
 bool example() {
   auto json = R"+( {
     "5f08a730b280e54fd1e75a7046b93fdc": {
@@ -3087,7 +3207,7 @@ bool example() {
 
 * Example 3: CRT
 
-```C++
+```cpp
 
 bool example() {
   padded_string padded_input_json = R"([
@@ -3164,7 +3284,7 @@ bool example() {
 
 * Example 4: Passing an array to a function
 
-```C++
+```cpp
 
 #include "simdjson.h"
 #include <iostream>
@@ -3259,13 +3379,13 @@ Performance tips
     }
   ```
 - If possible, refer to each object and array in your code once. For example, the following code repeatedly refers to the `"data"` key to create an object...
-	```C++
+	```cpp
 	std::string_view make = o["data"]["make"];
 	std::string_view model = o["data"]["model"];
 	std::string_view year = o["data"]["year"];
   ```
   We expect that it is more efficient to access the `"data"` key once:
-  ```C++
+  ```cpp
 	simdjson::ondemand::object data = o["data"];
 	std::string_view model = data["model"];
 	std::string_view year = data["year"];

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

@@ -14,6 +14,7 @@ speed and high convenience.
   * [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)
+    + [Pretty formatted (fractured JSON)](#pretty-formatted-fractured-json)
 
 Overview: string_builder
 ---------------------------
@@ -60,7 +61,7 @@ The later method (`view()`) is recommended.  For performance reasons, we expect
 Example: string_builder
 ---------------------------
 
-```C++
+```cpp
 struct Car {
     std::string make;
     std::string model;
@@ -332,7 +333,7 @@ pattern:
 
 ### Customization
 
-If you want to serialize a value in a custome way, you can do it with a
+If you want to serialize a value in a custom way, you can do it with a
 `tag_invoke` specialization like the following example which will map
 the year attribute to a string.
 
@@ -363,4 +364,50 @@ void tag_invoke(serialize_tag, builder_type &builder, const Car& car) {
 }
 
 } // namespace simdjson
-```
+```
+
+### Pretty formatted (fractured JSON)
+
+In some instances, you may want your JSON to be more readable. For this pupose, we also
+support the Fractured JSON standard.
+
+```Cpp
+  TableTestData data{
+    {{1, "Alice", true}, {2, "Bob", false}, {3, "Carol", true}, {4, "Dave", false}}
+  };
+
+  fractured_json_options opts;
+  opts.enable_table_format = true;
+  opts.min_table_rows = 3;
+
+  std::string formatted = simdjson::to_fractured_json_string(data, opts);
+```
+
+The result might be as follows.
+
+```json
+{
+    "records": [
+        { "active": true , "id": 1, "name": "Alice" },
+        { "active": false, "id": 2, "name": "Bob" },
+        { "active": true , "id": 3, "name": "Carol" },
+        { "active": false, "id": 4, "name": "Dave" }
+    ]
+}
+```
+
+The `fractured_json_options` struct allows you to customize the formatting behavior. It includes the following options:
+
+- `max_total_line_length` (default: 120): Maximum total characters per line. Content exceeding this will be expanded to multiple lines.
+- `max_inline_length` (default: 80): Maximum length for inlined elements. Simple arrays/objects shorter than this may be rendered inline.
+- `max_inline_complexity` (default: 2): Maximum nesting depth for inline rendering. Elements with complexity exceeding this will be expanded. Complexity 0 = scalar, 1 = flat array/object, 2 = one level of nesting.
+- `max_compact_array_complexity` (default: 1): Maximum complexity for compact array formatting. Arrays with elements of this complexity or less may have multiple items per line.
+- `indent_spaces` (default: 4): Number of spaces per indentation level.
+- `enable_table_format` (default: true): Enable tabular formatting for arrays of similar objects. When enabled, arrays of objects with identical keys are formatted as aligned tables.
+- `min_table_rows` (default: 3): Minimum number of rows to trigger table mode.
+- `table_similarity_threshold` (default: 0.8): Similarity threshold for table detection. Objects must share at least this fraction of keys to be formatted as a table.
+- `enable_compact_multiline` (default: true): Enable compact multiline arrays. When enabled, arrays of simple elements may have multiple items per line.
+- `max_items_per_line` (default: 10): Maximum array items per line in compact mode.
+- `simple_bracket_padding` (default: true): Add space inside brackets for simple containers. When true: `{ "key": "value" }`, when false: `{"key": "value"}`.
+- `colon_padding` (default: true): Add space after colons. When true: `"key": "value"`, when false: `"key":"value"`.
+- `comma_padding` (default: true): Add space after commas in inline content. When true: `[1, 2, 3]`, when false: `[1,2,3]`.

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
+expectation 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

@@ -41,7 +41,7 @@ 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
 ```
@@ -49,21 +49,39 @@ 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);
+```
+
+[You can similarly fetch a file from a URL to a padded string](https://github.com/simdjson/curltostring) using our `simdjson::padded_string_builder`.
+
+(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
 ```
@@ -83,7 +101,7 @@ 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:
 
-```c++
+```cpp
 std::string json = "[1]";
 dom::element doc = parser.parse(simdjson::pad(json));
 ```
@@ -107,6 +125,22 @@ Further, they may use the AreFileApisANSI function to determine whether
 the filename is interpreted using the ANSI or the system default OEM
 codepage, and they may call SetFileApisToOEM accordingly.
 
+
+**Advanced feature:**
+On non-Windows systems, you can use memory-file mapping to create a `simdjson::padded_string_view`
+from a file on disk.
+
+```cpp
+// if the macro _WIN32 is defined, this will not work since we do not support Windows
+simdjson::padded_memory_map map(TWITTER_JSON);
+if (!map.is_valid()) { /* handle error */ }
+simdjson::padded_string_view view = map.view(); // view is usable while padded_memory_map is in scope
+ondemand::document doc = parser.iterate(view); // parse the JSON
+```
+
+Using memory-file mapping requires some care. The file should not be modified while you are
+accessing it.
+
 Using the Parsed JSON
 ---------------------
 
@@ -117,8 +151,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
@@ -152,7 +187,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 ] },
@@ -185,7 +221,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}  }
@@ -207,7 +243,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;
@@ -221,7 +257,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
@@ -234,7 +270,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;
@@ -251,7 +287,7 @@ C++20 Support
 
 simdjson library also supports some C++20 feature including `std::ranges`:
 
-```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 ] },
@@ -270,7 +306,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 ] },
@@ -291,7 +327,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 ] },
@@ -313,11 +349,11 @@ JSONPath
 ------------
 
 
-The simdjson library supports a subset of [JSONPath](https://datatracker.ietf.org/doc/html/draft-normington-jsonpath-00) 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.
+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:
 
-```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 ] },
@@ -336,7 +372,7 @@ 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.,
 
-```c++
+```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;
@@ -428,7 +464,7 @@ 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); }
@@ -462,7 +498,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"
 
@@ -490,7 +526,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"
 
@@ -514,7 +550,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 ] },
@@ -561,7 +597,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}  }
@@ -594,7 +630,7 @@ for (dom::element elem : array) {
 
 And another one:
 
-```C++
+```cpp
   auto abstract_json = R"(
     {  "str" : { "123" : {"abc" : 3.14 } } } )"_padded;
   dom::parser parser;
@@ -608,7 +644,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) {
@@ -640,7 +676,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!
 ```
 
@@ -650,7 +686,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"
 
@@ -671,7 +707,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:
@@ -727,7 +763,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.
@@ -770,7 +806,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;
@@ -786,7 +822,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); }
@@ -817,7 +853,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]};
@@ -825,7 +861,7 @@ 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.
 

doc/implementation-selection.md

@@ -33,6 +33,9 @@ compiles *all* the implementations into the executable. On Intel, it will includ
 (icelake, haswell, westmere and fallback), on 64-bit ARM it will include just one since running dispatching is  unnecessary, and on PPC
 it will include 2 (ppc64 and fallback).
 
+On Loongson processors, LASX runtime dispatching is only enabled on GCC 15+, not on LLVM or older versions of GCC.
+Thus unless you compile specifically for LASX or use GCC 15+, you will not benefit from LASX support.
+
 If you know more about where you're going to run and want to save the space, you can disable any of
 these implementations at compile time with `-DSIMDJSON_IMPLEMENTATION_X=0` (where X is ICELAKE, HASWELL,
 WESTMERE, ARM64, PPC64, LSX, LASX and FALLBACK).
@@ -55,7 +58,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 +71,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 +79,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 +96,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 +105,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 +117,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.
 
@@ -132,7 +132,7 @@ E.g., `[1,2]{"32":1}` is recognized as two documents.
 Some official formats **(non-exhaustive list)**:
 - [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
@@ -140,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) {
@@ -152,6 +154,20 @@ for (auto doc : docs) {
 
 See [basics.md](basics.md#newline-delimited-json-ndjson-and-json-lines) for an overview of the API.
 
+
+**Advanced feature:**
+On non-Windows systems, you can use memory-file mapping to create a `simdjson::padded_string_view`
+from a file on disk.
+
+```cpp
+// If the macro _WIN32 is defined, this will not work since we do not support memory-file mapping
+// under Windows at this time.
+simdjson::padded_memory_map map(myfilename);
+if (!map.is_valid()) { /* handle error */ }
+simdjson::padded_string_view view = map.view(); // view is usable while padded_memory_map is in scope
+ondemand::document doc = parser.iterate(view); // parse the JSON
+```
+
 ## Use cases
 
 From [jsonlines.org](http://jsonlines.org/examples/):
@@ -197,7 +213,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;
@@ -238,7 +254,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;
@@ -267,7 +283,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;
@@ -314,7 +330,7 @@ the simdjson library.
 
 Consider a custom class `Car`:
 
-```C++
+```cpp
 struct Car {
   std::string make;
   std::string model;
@@ -328,7 +344,7 @@ You may support deserializing directly from a JSON value or document to your own
 by defining a single `tag_invoke` function:
 
 
-```C++
+```cpp
 namespace simdjson {
 // This tag_invoke MUST be inside simdjson namespace
 template <typename simdjson_value>
@@ -370,7 +386,7 @@ 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:
 
-```C++
+```cpp
   padded_string json =
       R"( { "make": "Toyota", "model": "Camry",  "year": 2018,
        "tire_pressure": [ 40.1, 39.9 ] }
@@ -391,7 +407,7 @@ such as a `std::vector<Car>` like so if you support exceptions:
 Otherwise you may use this longer version for explicit handling of errors:
 
 
-```C++
+```cpp
   std::vector<Car> cars;
   for(auto doc : stream) {
     Car c;
@@ -401,4 +417,4 @@ Otherwise you may use this longer version for explicit handling of errors:
     }
     cars.push_back(c);
   }
-```
+```

doc/ondemand_design.md

@@ -23,7 +23,7 @@ applications with a computation efficiency that is difficult to surpass.
 
 A code example illustrates our API from a programmer's point of view:
 
-```c++
+```cpp
 ondemand::parser parser;
 auto doc = parser.iterate(json);
 for (auto tweet : doc["statuses"]) {
@@ -109,7 +109,7 @@ The DOM approach was the only way to parse JSON documents up to version 0.6 of t
 Our DOM API looks similar to our On-Demand example, except
 it calls `parse` instead of `iterate`:
 
-```c++
+```cpp
 dom::parser parser;
 auto doc = parser.parse(json);
 for (auto tweet : doc["statuses"]) {
@@ -157,7 +157,7 @@ examples. To make it short enough to use as an example at all, it has heavily re
 a part of the problem (does not get user.screen_name), it has bugs (it does not handle sub-objects
 in a tweet at all), and it uses a theoretical, simple event-based API that minimizes ceremony.
 
-```c++
+```cpp
 struct twitter_callbacks {
   bool in_statuses;
   bool in_tweet;
@@ -284,14 +284,14 @@ To help visualize the algorithm, we'll walk through the example C++ given at the
 
    This declaration does not allocate any memory; that will happen in the next step.
 
-   ```c++
+   ```cpp
    ondemand::parser parser;
    ```
 
 2. We then start iterating the JSON document by allocating internal parser buffers, preprocessing
    the JSON, and initializing the iterator.
 
-   ```c++
+   ```cpp
    auto doc = parser.iterate(json);
    ```
 
@@ -337,14 +337,14 @@ To help visualize the algorithm, we'll walk through the example C++ given at the
 3. We iterate over the "statuses" field using a typical C++ iterator, reading past the initial
    `{ "statuses": [ {`.
 
-   ```c++
+   ```cpp
    for (ondemand::object tweet : doc["statuses"]) {
    ```
 
    This shorthand does a lot, and it is helpful to see what it expands to.
    Comments in front of each one explain what's going on:
 
-   ```c++
+   ```cpp
    // Validate that the top-level value is an object: check for {. Increase depth to 2 (root > field).
    ondemand::object top = doc.get_object();
 
@@ -396,7 +396,7 @@ To help visualize the algorithm, we'll walk through the example C++ given at the
 
 4. We get the `"text"` field as a string.
 
-   ```c++
+   ```cpp
    std::string_view text        = tweet["text"];
    ```
 
@@ -435,7 +435,7 @@ To help visualize the algorithm, we'll walk through the example C++ given at the
 
 4. We get the `"screen_name"` from the `"user"` object.
 
-   ```c++
+   ```cpp
       ondemand::object user        = tweet["user"];
       screen_name                  = user["screen_name"];
    ```
@@ -469,7 +469,7 @@ To help visualize the algorithm, we'll walk through the example C++ given at the
 
 5. We get `"retweet_count"` as an unsigned integer.
 
-   ```c++
+   ```cpp
    uint64_t         retweets    = tweet["retweet_count"];
    ```
 
@@ -513,7 +513,7 @@ To help visualize the algorithm, we'll walk through the example C++ given at the
 
 6. We loop to the next tweet.
 
-   ```c++
+   ```cpp
    for (ondemand::object tweet : doc["statuses"]) {
      ...
    }
@@ -521,7 +521,7 @@ To help visualize the algorithm, we'll walk through the example C++ given at the
 
    The relevant parts of the loop  are:
 
-   ```c++
+   ```cpp
    while (iter != statuses.end()) {
      ondemand::object tweet = *iter;
      ...
@@ -545,7 +545,7 @@ To help visualize the algorithm, we'll walk through the example C++ given at the
      "statuses": [
        { "id": 1, "text": "first!", "user": { "screen_name": "lemire", "name": "Daniel" }, "retweet_count": 40 },
        { "id": 2, "text": "second!", "user": { "screen_name": "jkeiser2", "name": "John" }, "retweet_count": 3 }
-                                                                                                               ^ (depth 3 - root > statuses > tweet)
+         ^ (depth 4 - root > statuses > tweet > field)
      ],
      "search_metadata": { "count": 2 }
    }
@@ -566,7 +566,7 @@ To help visualize the algorithm, we'll walk through the example C++ given at the
 
 8. The loop ends. Recall the relevant parts of the statuses loop:
 
-   ```c++
+   ```cpp
    while (iter != statuses.end()) {
      ondemand::object tweet = *iter;
      ...
@@ -610,7 +610,7 @@ When the user requests strings, we unescape them to a single string buffer much
 so that users enjoy the same string performance as the core simdjson. We do not write the length to the
 string buffer, however; that is stored in the `string_view` instance we return to the user.
 
-```C++
+```cpp
   ondemand::parser parser;
   auto doc = parser.iterate(json);
   std::set<std::string_view> default_users;
@@ -645,7 +645,7 @@ from the `unescaped_key()` method has a lifecycle tied to the `parser` instance:
 is destroyed or reused with another document, the `std::string_view` instance becomes invalid.
 
 
-```C++
+```cpp
 auto doc = parser.iterate(json);
 for(auto field : doc.get_object())  {
       std::string_view keyv = field.unescaped_key();
@@ -670,9 +670,11 @@ in production systems:
   Some care is needed when using the On-Demand API in scenarios where you need to access several sibling arrays or objects because
   only one object or array can be active at any one time. Let us consider the following example:
 
-```C++
+```cpp
     ondemand::parser parser;
+    //  R"( ... )" is a C++ raw string literal.
     const padded_string json = R"({ "parent": {"child1": {"name": "John"} , "child2": {"name": "Daniel"}} })"_padded;
+    // _padded returns an simdjson padded_string instance
     auto doc = parser.iterate(json);
     ondemand::object parent = doc["parent"];
     // parent owns the focus
@@ -688,7 +690,7 @@ in production systems:
 
 A correct usage is given by the following example:
 
-```C++
+```cpp
     ondemand::parser parser;
     const padded_string json = R"({ "parent": {"child1": {"name": "John"} , "child2": {"name": "Daniel"}} })"_padded;
     auto doc = parser.iterate(json);
@@ -754,7 +756,7 @@ Some users wish to run at the best possible speed. Under recent Intel and AMD pr
 
 Given that the On-Demand API offer limited runtime dispatching, it matters that your code is compiled against a specific CPU target. You should verify that the code is compiled against the target you expect. Thankfully, the simdjson library will tell you exactly what it detects as an implementation: `icelake` (AVX512 x64 processors), `haswell` (AVX2 x64 processors), `westmere` (SSE4 x64 processors), `arm64` (64-bit ARM), `ppc64` (64-bit POWER), `lasx` (LoongArch), `lsx` (LoongArch),  `fallback` (others). Under x64 processors, many programmers will want to target `haswell` whereas under ARM, most programmers will want to target `arm64` (and it should do so automatically). The `fallback` is probably only good for testing purposes, not for deployment.
 
-```C++
+```cpp
   std::cout << simdjson::builtin_implementation()->name() << std::endl;
 ```
 

doc/parse_many.md

@@ -132,7 +132,7 @@ Whitespace Characters:
 Some official formats **(non-exhaustive list)**:
 - [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
@@ -184,7 +184,7 @@ You may also call the `source()` method to get a `std::string_view` instance on
 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::dom::parser parser;
     simdjson::dom::document_stream stream;
@@ -217,6 +217,20 @@ got full document at 29
 ```
 
 
+
+**Advanced feature:**
+On non-Windows systems, you can use memory-file mapping to create a `simdjson::padded_string_view`
+from a file on disk.
+
+```cpp
+// If the macro _WIN32 is defined, this will not work since we do not support memory-file mapping
+// under Windows at this time.
+simdjson::padded_memory_map map(myfilename);
+if (!map.is_valid()) { /* handle error */ }
+simdjson::padded_string_view view = map.view(); // view is usable while padded_memory_map is in scope
+ondemand::document doc = parser.iterate(view); // parse the JSON
+```
+
 Incomplete streams
 -----------
 
@@ -225,7 +239,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::dom::parser parser;
     simdjson::dom::document_stream stream;

doc/performance.md

@@ -47,7 +47,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
 ondemand::parser parser;
 
 // This initializes buffers  big enough to handle this JSON.
@@ -71,14 +71,14 @@ Reusing string buffers
 
 We recommend against creating many `std::string` or `simdjson::padded_string` instances to store the JSON content in your application. [Creating many non-trivial objects is convenient but often surprisingly slow](https://lemire.me/blog/2020/08/08/performance-tip-constructing-many-non-trivial-objects-is-slow/). Instead, as much as possible, you should allocate (once or a few times) reusable memory buffers where you write your JSON content. If you have a buffer `json_str` (of type `char*`) allocated for  `capacity` bytes and you store a JSON document spanning `length` bytes, you can pass it to simdjson as follows:
 
-```c++
+```cpp
  auto doc = parser.iterate(padded_string_view(json_str, length, capacity));
 ```
 
 or simply
 
 
-```c++
+```cpp
  auto doc = parser.iterate(json_str, length, capacity);
 ```
 
@@ -89,7 +89,7 @@ Server Loops: Long-Running Processes and Memory Capacity
 The On-Demand approach also automatically expands its memory capacity when larger documents are parsed. However, for longer processes where very large files are processed (such as server loops), this capacity is not resized down. On-Demand also lets you adjust the maximal capacity that the parser can process:
 
 * You can set an upper bound (*max_capacity*) when construction the parser:
-```C++
+```cpp
     ondemand::parser parser(1000*1000);  // Never grows past documents > 1 MB
     auto doc = parser.iterate(json);
     for (web_request request : listen()) {
@@ -105,7 +105,7 @@ The On-Demand approach also automatically expands its memory capacity when large
 The capacity will grow as the parser encounters larger documents up to 1 MB.
 
 * You can also allocate a *fixed capacity* that will never grow:
-```C++
+```cpp
     ondemand::parser parser(1000*1000);
     parser.allocate(1000*1000)  // Fix the capacity to 1 MB
     auto doc = parser.iterate(json);
@@ -297,4 +297,62 @@ int main() {
   }
   return EXIT_SUCCESS;
 }
+```
+
+Further, whenever you allocate N bytes, memory allocators tend to allocate more memory, without you necessarily knowing about it. Under linux, you can use the `malloc_usable_size` function to see how much memory was actually allocated.
+Under an Apple plateform, you can  `malloc_size`. The following program illustrates the usage.
+
+```cpp
+#include <iostream>
+#include <cstddef>
+#include <memory>
+#include <cstdlib>
+#ifdef __APPLE__
+#include <malloc/malloc.h>  // for malloc_size on macOS
+#endif
+#ifdef __linux__
+#include <malloc.h> // for malloc_usable_size on Linux
+#endif
+size_t get_usable_size(void* ptr) {
+#ifdef __linux__
+    return malloc_usable_size(ptr);
+#elif defined(__APPLE__)
+    return malloc_size(ptr);
+#else
+    return 0;  // Unsupported platform
+#endif
+}
+
+int main() {
+    std::cout << "Demonstrating allocation overhead and rounding with operator new\n\n";
+
+#ifdef __linux__
+    std::cout << "Platform: Linux\n";
+#elif defined(__APPLE__)
+    std::cout << "Platform: macOS (using malloc_size)\n";
+#else
+    std::cout << "Platform: Other/unsupported (usable size will show 0)\n";
+#endif
+
+    std::cout << "Requested size | Actual usable size\n";
+    std::cout << "---------------|-------------------\n";
+    size_t total_requested = 0;
+    size_t total_usable = 0;
+    for (size_t requested = 1; requested <= 4096; requested++) {
+        total_requested += requested;
+        std::unique_ptr<char[]> ptr(new char[requested]);  // Allocate
+        size_t usable = get_usable_size(ptr.get());  // Get usable size
+        total_usable += usable;
+
+        std::cout << requested << "\t       | " << usable << "\n";
+    }
+    std::cout << "---------------|-------------------\n";
+    std::cout << "Total requested: " << total_requested << " bytes\n";
+    std::cout << "Total usable:    " << total_usable << " bytes\n";
+    std::cout << "Total overhead:  " << (total_usable - total_requested) << " bytes\n";
+    std::cout << "Percentage overhead: "
+              << ((total_usable - total_requested) * 100.0 / total_requested) << " %\n";
+
+    return EXIT_SUCCESS;
+}
 ```

fuzz/fuzz_minify.cpp

@@ -8,16 +8,11 @@
  * Minifies by first parsing, then minifying.
  */
 extern "C" int LLVMFuzzerTestOneInput(const uint8_t *Data, size_t Size) {
-
-    auto begin = as_chars(Data);
-    auto end = begin + Size;
-
-    std::string str(begin, end);
+    simdjson::padded_string str(reinterpret_cast<const char *>(Data), Size);
     simdjson::dom::parser parser;
     simdjson::dom::element elem;
     auto error = parser.parse(str).get(elem);
     if (error) { return 0; }
-
     std::string minified = simdjson::minify(elem);
     (void)minified;
     return 0;

fuzz/ossfuzz.sh

@@ -35,7 +35,7 @@ cmake .. \
 -DSIMDJSON_DISABLE_DEPRECATED_API=On \
 -DSIMDJSON_FUZZ_LDFLAGS=$LIB_FUZZING_ENGINE
 
-cmake --build . --target all_fuzzers
+cmake --build . --target all_fuzzers all_tests
 
 cp fuzz/fuzz_* $OUT
 

include/simdjson.h

@@ -52,7 +52,13 @@
 #include "simdjson/padded_string_view-inl.h"
 
 #include "simdjson/dom.h"
+#include "simdjson/builder.h"
 #include "simdjson/ondemand.h"
 #include "simdjson/convert.h"
 #include "simdjson/convert-inl.h"
+
+// Compile-time JSON parsing (C++26 P2996 reflection)
+#include "simdjson/compile_time_json.h"
+#include "simdjson/compile_time_json-inl.h"
+
 #endif // SIMDJSON_H

include/simdjson/arm64/builder.h

@@ -0,0 +1,8 @@
+#ifndef SIMDJSON_ARM64_BUILDER_H
+#define SIMDJSON_ARM64_BUILDER_H
+
+#include "simdjson/arm64/begin.h"
+#include "simdjson/generic/builder/amalgamated.h"
+#include "simdjson/arm64/end.h"
+
+#endif // SIMDJSON_ARM64_BUILDER_H

include/simdjson/arm64/simd.h

@@ -428,6 +428,7 @@ namespace {
     static constexpr int NUM_CHUNKS = 64 / sizeof(simd8<T>);
     static_assert(NUM_CHUNKS == 4, "ARM kernel should use four registers per 64-byte block.");
     const simd8<T> chunks[NUM_CHUNKS];
+    template<int idx> simd8<uint8_t> get() const { return idx < NUM_CHUNKS ? chunks[idx] : simd8<T>(); }
 
     simd8x64(const simd8x64<T>& o) = delete; // no copy allowed
     simd8x64<T>& operator=(const simd8<T>& other) = delete; // no assignment allowed

include/simdjson/builder.h

@@ -0,0 +1,14 @@
+#ifndef SIMDJSON_BUILDER_H
+#define SIMDJSON_BUILDER_H
+
+#include "simdjson/builtin/builder.h"
+
+namespace simdjson {
+  /**
+   * @copydoc simdjson::builtin::builder
+   */
+  namespace builder = builtin::builder;
+
+} // namespace simdjson
+
+#endif // SIMDJSON_BUILDER_H

include/simdjson/builtin.h

@@ -20,10 +20,12 @@
 #include "simdjson/ppc64.h"
 #elif SIMDJSON_BUILTIN_IMPLEMENTATION_IS(westmere)
 #include "simdjson/westmere.h"
-#elif SIMDJSON_BUILTIN_IMPLEMENTATION_IS(lsx)
-#include "simdjson/lsx.h"
 #elif SIMDJSON_BUILTIN_IMPLEMENTATION_IS(lasx)
 #include "simdjson/lasx.h"
+#elif SIMDJSON_BUILTIN_IMPLEMENTATION_IS(lsx)
+#include "simdjson/lsx.h"
+#elif SIMDJSON_BUILTIN_IMPLEMENTATION_IS(rvv_vls)
+#include "simdjson/rvv-vls.h"
 #else
 #error Unknown SIMDJSON_BUILTIN_IMPLEMENTATION
 #endif

include/simdjson/builtin/base.h

@@ -21,6 +21,8 @@ namespace simdjson {
   namespace lsx {}
 #elif SIMDJSON_BUILTIN_IMPLEMENTATION_IS(lasx)
   namespace lasx {}
+#elif SIMDJSON_BUILTIN_IMPLEMENTATION_IS(rvv_vls)
+  namespace rvv_vls {}
 #else
 #error Unknown SIMDJSON_BUILTIN_IMPLEMENTATION
 #endif

include/simdjson/builtin/builder.h

@@ -0,0 +1,42 @@
+#ifndef SIMDJSON_BUILTIN_BUILDER_H
+#define SIMDJSON_BUILTIN_BUILDER_H
+
+#include "simdjson/builtin.h"
+#include "simdjson/builtin/base.h"
+
+#include "simdjson/generic/builder/dependencies.h"
+
+#define SIMDJSON_CONDITIONAL_INCLUDE
+
+#if SIMDJSON_BUILTIN_IMPLEMENTATION_IS(arm64)
+#include "simdjson/arm64/builder.h"
+#elif SIMDJSON_BUILTIN_IMPLEMENTATION_IS(fallback)
+#include "simdjson/fallback/builder.h"
+#elif SIMDJSON_BUILTIN_IMPLEMENTATION_IS(haswell)
+#include "simdjson/haswell/builder.h"
+#elif SIMDJSON_BUILTIN_IMPLEMENTATION_IS(icelake)
+#include "simdjson/icelake/builder.h"
+#elif SIMDJSON_BUILTIN_IMPLEMENTATION_IS(ppc64)
+#include "simdjson/ppc64/builder.h"
+#elif SIMDJSON_BUILTIN_IMPLEMENTATION_IS(westmere)
+#include "simdjson/westmere/builder.h"
+#elif SIMDJSON_BUILTIN_IMPLEMENTATION_IS(lsx)
+#include "simdjson/lsx/builder.h"
+#elif SIMDJSON_BUILTIN_IMPLEMENTATION_IS(lasx)
+#include "simdjson/lasx/builder.h"
+#elif SIMDJSON_BUILTIN_IMPLEMENTATION_IS(rvv_vls)
+#include "simdjson/rvv-vls/builder.h"
+#else
+#error Unknown SIMDJSON_BUILTIN_IMPLEMENTATION
+#endif
+
+#undef SIMDJSON_CONDITIONAL_INCLUDE
+
+namespace simdjson {
+  /**
+   * @copydoc simdjson::SIMDJSON_BUILTIN_IMPLEMENTATION::builder
+   */
+  namespace builder = SIMDJSON_BUILTIN_IMPLEMENTATION::builder;
+} // namespace simdjson
+
+#endif // SIMDJSON_BUILTIN_BUILDER_H

include/simdjson/builtin/implementation.h

@@ -23,6 +23,8 @@
 #include "simdjson/lsx/implementation.h"
 #elif SIMDJSON_BUILTIN_IMPLEMENTATION_IS(lasx)
 #include "simdjson/lasx/implementation.h"
+#elif SIMDJSON_BUILTIN_IMPLEMENTATION_IS(rvv_vls)
+#include "simdjson/rvv-vls/implementation.h"
 #else
 #error Unknown SIMDJSON_BUILTIN_IMPLEMENTATION
 #endif
@@ -39,4 +41,4 @@ namespace simdjson {
   const implementation * builtin_implementation();
 } // namespace simdjson
 
-#endif // SIMDJSON_BUILTIN_IMPLEMENTATION_H
+#endif // SIMDJSON_BUILTIN_IMPLEMENTATION_H

include/simdjson/builtin/ondemand.h

@@ -24,6 +24,8 @@
 #include "simdjson/lsx/ondemand.h"
 #elif SIMDJSON_BUILTIN_IMPLEMENTATION_IS(lasx)
 #include "simdjson/lasx/ondemand.h"
+#elif SIMDJSON_BUILTIN_IMPLEMENTATION_IS(rvv_vls)
+#include "simdjson/rvv-vls/ondemand.h"
 #else
 #error Unknown SIMDJSON_BUILTIN_IMPLEMENTATION
 #endif
@@ -37,4 +39,4 @@ namespace simdjson {
   namespace ondemand = SIMDJSON_BUILTIN_IMPLEMENTATION::ondemand;
 } // namespace simdjson
 
-#endif // SIMDJSON_BUILTIN_ONDEMAND_H
+#endif // SIMDJSON_BUILTIN_ONDEMAND_H

include/simdjson/common_defs.h

@@ -289,7 +289,9 @@ namespace std {
 // when the compiler is optimizing.
 // We only set SIMDJSON_DEVELOPMENT_CHECKS if both __OPTIMIZE__
 // and NDEBUG are not defined.
-#if !defined(__OPTIMIZE__) && !defined(NDEBUG)
+// We recognize _DEBUG as overriding __OPTIMIZE__ so that if both
+// __OPTIMIZE__ and _DEBUG are defined, we still set SIMDJSON_DEVELOPMENT_CHECKS.
+#if ((!defined(__OPTIMIZE__) || defined(_DEBUG)) && !defined(NDEBUG))
 #define SIMDJSON_DEVELOPMENT_CHECKS 1
 #endif // __OPTIMIZE__
 #endif // _MSC_VER

include/simdjson/compile_time_json.h

@@ -0,0 +1,75 @@
+/**
+ * @file compile_time_json.h
+ * @brief Compile-time JSON parsing using C++26 reflection with
+ * std::meta::substitute()
+ */
+
+#ifndef SIMDJSON_GENERIC_COMPILE_TIME_JSON_H
+#define SIMDJSON_GENERIC_COMPILE_TIME_JSON_H
+
+#if SIMDJSON_STATIC_REFLECTION
+
+#include <algorithm>
+#include <array>
+#include <charconv>
+#include <cstdint>
+#include <expected>
+#include <meta>
+#include <string>
+#include <string_view>
+#include <vector>
+
+namespace simdjson {
+namespace compile_time {
+
+/**
+ * @brief Compile-time JSON parser. This function parses the provided JSON
+ * string at compile time and returns a custom struct type representing the JSON
+ * object.
+ *
+ * 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:
+ *    [
+ *     { "name": "Alice", "age": 30 },
+ *     { "name": "Bob", "age": 25 },
+ *     { "name": "Charlie", "age": 35 }
+ *   ]
+ *   but the following is not:
+ *   [
+ *     { "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 } 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.
+ *
+ * This function is subject to change in the future.
+ */
+template <constevalutil::fixed_string json_str> consteval auto parse_json();
+
+} // namespace compile_time
+} // namespace simdjson
+
+
+template <simdjson::constevalutil::fixed_string str>
+consteval auto operator ""_json() {
+  return simdjson::compile_time::parse_json<str>();
+}
+
+#endif // SIMDJSON_STATIC_REFLECTION
+#endif // SIMDJSON_GENERIC_COMPILE_TIME_JSON_H

include/simdjson/compiler_check.h

@@ -13,6 +13,11 @@
 #endif
 #endif
 
+// C++ 26
+#if !defined(SIMDJSON_CPLUSPLUS26) && (SIMDJSON_CPLUSPLUS >= 202402L) // update when the standard is finalized
+#define SIMDJSON_CPLUSPLUS26 1
+#endif
+
 // C++ 23
 #if !defined(SIMDJSON_CPLUSPLUS23) && (SIMDJSON_CPLUSPLUS >= 202302L)
 #define SIMDJSON_CPLUSPLUS23 1
@@ -114,5 +119,4 @@
 #define SIMDJSON_CONSTEVAL 0
 #endif // defined(__cpp_consteval) && __cpp_consteval >= 201811L && defined(__cpp_lib_constexpr_string) && __cpp_lib_constexpr_string >= 201907L
 #endif // !defined(SIMDJSON_CONSTEVAL)
-
 #endif // SIMDJSON_COMPILER_CHECK_H

include/simdjson/concepts.h

@@ -143,6 +143,25 @@ concept container_but_not_string =
   std::ranges::input_range<T> && !string_like<T> && !concepts::string_view_keyed_map<T>;
 
 
+
+// Concept: Indexable container that is not a string or associative container
+// Accepts: std::vector, std::array, std::deque (have operator[], value_type, not string_like)
+// Rejects: std::string (string_like), std::list (no operator[]), std::map (has key_type)
+template<typename Container>
+concept indexable_container = requires {
+  typename Container::value_type;
+  requires !concepts::string_like<Container>;
+  requires !requires { typename Container::key_type; };  // Reject maps/sets
+  requires requires(Container& c, std::size_t i) {
+    { c[i] } -> std::convertible_to<typename Container::value_type>;
+  };
+};
+
+
+// Variable template to use with std::meta::substitute
+template<typename Container>
+constexpr bool indexable_container_v = indexable_container<Container>;
+
 } // namespace concepts
 
 

include/simdjson/constevalutil.h

@@ -51,9 +51,8 @@ consteval std::string consteval_to_quoted_escaped(std::string_view input) {
 
 
 #if SIMDJSON_SUPPORTS_CONCEPTS
-template <std::size_t N>
+template <size_t N>
 struct fixed_string {
-    constexpr fixed_string() : data{} {}  // Default constructor for buffers
     constexpr fixed_string(const char (&str)[N])  {
         for (std::size_t i = 0; i < N; ++i) {
             data[i] = str[i];
@@ -61,6 +60,20 @@ struct fixed_string {
     }
     char data[N];
     constexpr std::string_view view() const { return {data, N - 1}; }
+    constexpr size_t size() const { return N ; }
+    constexpr operator std::string_view() const { return view(); }
+    constexpr char operator[](std::size_t index) const { return data[index]; }
+    constexpr bool operator==(const fixed_string& other) const {
+        if (N != other.size()) {
+            return false;
+        }
+        for (std::size_t i = 0; i < N; ++i) {
+            if (data[i] != other.data[i]) {
+                return false;
+            }
+        }
+        return true;
+    }
 };
 template <std::size_t N>
 fixed_string(const char (&)[N]) -> fixed_string<N>;

include/simdjson/dom.h

@@ -9,6 +9,7 @@
 #include "simdjson/dom/object.h"
 #include "simdjson/dom/parser.h"
 #include "simdjson/dom/serialization.h"
+#include "simdjson/dom/fractured_json.h"
 
 // Inline functions
 #include "simdjson/dom/array-inl.h"
@@ -19,5 +20,6 @@
 #include "simdjson/dom/parser-inl.h"
 #include "simdjson/internal/tape_ref-inl.h"
 #include "simdjson/dom/serialization-inl.h"
+#include "simdjson/dom/fractured_json-inl.h"
 
 #endif // SIMDJSON_DOM_H

include/simdjson/dom/array.h

@@ -111,7 +111,7 @@ public:
   inline simdjson_result<element> at_pointer(std::string_view json_pointer) const noexcept;
 
   /**
-   * Recursive function which processes the json path of each child element
+   * Recursive function which processes the JSON path of each child element
    */
   inline void process_json_path_of_child_elements(std::vector<element>::iterator& current, std::vector<element>::iterator& end, const std::string_view& path_suffix, std::vector<element>& accumulator) const noexcept;
 
@@ -126,7 +126,7 @@ public:
    * JSONPath queries that trivially convertible to JSON Pointer queries: key
    * names and array indices.
    *
-   * https://datatracker.ietf.org/doc/html/draft-normington-jsonpath-00
+   * https://www.rfc-editor.org/rfc/rfc9535 (RFC 9535)
    *
    * @return The value associated with the given JSONPath expression, or:
    *         - INVALID_JSON_POINTER if the JSONPath to JSON Pointer conversion fails

include/simdjson/dom/document_stream.h

@@ -74,7 +74,7 @@ public:
   /**
    * Construct an uninitialized document_stream.
    *
-   *  ```c++
+   *  ```cpp
    *  document_stream docs;
    *  error = parser.parse_many(json).get(docs);
    *  ```

include/simdjson/dom/element.h

@@ -408,7 +408,7 @@ public:
    * JSONPath queries that trivially convertible to JSON Pointer queries: key
    * names and array indices.
    *
-   * https://datatracker.ietf.org/doc/html/draft-normington-jsonpath-00
+   * https://www.rfc-editor.org/rfc/rfc9535 (RFC 9535)
    *
    * @return The value associated with the given JSONPath expression, or:
    *         - INVALID_JSON_POINTER if the JSONPath to JSON Pointer conversion fails

include/simdjson/dom/fractured_json.h

@@ -0,0 +1,159 @@
+#ifndef SIMDJSON_DOM_FRACTURED_JSON_H
+#define SIMDJSON_DOM_FRACTURED_JSON_H
+
+#include "simdjson/dom/base.h"
+#include "simdjson/dom/element.h"
+
+namespace simdjson {
+
+/**
+ * Configuration options for FracturedJson formatting.
+ *
+ * FracturedJson intelligently chooses between different layout strategies
+ * (inline, compact multiline, table, expanded) based on content complexity,
+ * length, and structure similarity.
+ */
+struct fractured_json_options {
+  /**
+   * Maximum total characters per line (default: 120).
+   * Content exceeding this will be expanded to multiple lines.
+   */
+  size_t max_total_line_length = 120;
+
+  /**
+   * Maximum length for inlined elements (default: 80).
+   * Simple arrays/objects shorter than this may be rendered inline.
+   */
+  size_t max_inline_length = 80;
+
+  /**
+   * Maximum nesting depth for inline rendering (default: 2).
+   * Elements with complexity exceeding this will be expanded.
+   * Complexity 0 = scalar, 1 = flat array/object, 2 = one level of nesting.
+   */
+  size_t max_inline_complexity = 2;
+
+  /**
+   * Maximum complexity for compact array formatting (default: 1).
+   * Arrays with elements of this complexity or less may have multiple
+   * items per line.
+   */
+  size_t max_compact_array_complexity = 1;
+
+  /**
+   * Number of spaces per indentation level (default: 4).
+   */
+  size_t indent_spaces = 4;
+
+  /**
+   * Enable tabular formatting for arrays of similar objects (default: true).
+   * When enabled, arrays of objects with identical keys are formatted
+   * as aligned tables.
+   */
+  bool enable_table_format = true;
+
+  /**
+   * Minimum number of rows to trigger table mode (default: 3).
+   */
+  size_t min_table_rows = 3;
+
+  /**
+   * Similarity threshold for table detection (default: 0.8).
+   * Objects must share at least this fraction of keys to be formatted
+   * as a table.
+   */
+  double table_similarity_threshold = 0.8;
+
+  /**
+   * Enable compact multiline arrays (default: true).
+   * When enabled, arrays of simple elements may have multiple items
+   * per line.
+   */
+  bool enable_compact_multiline = true;
+
+  /**
+   * Maximum array items per line in compact mode (default: 10).
+   */
+  size_t max_items_per_line = 10;
+
+  /**
+   * Add space inside brackets for simple containers (default: true).
+   * When true: { "key": "value" }
+   * When false: {"key": "value"}
+   */
+  bool simple_bracket_padding = true;
+
+  /**
+   * Add space after colons (default: true).
+   * When true: "key": "value"
+   * When false: "key":"value"
+   */
+  bool colon_padding = true;
+
+  /**
+   * Add space after commas in inline content (default: true).
+   * When true: [1, 2, 3]
+   * When false: [1,2,3]
+   */
+  bool comma_padding = true;
+};
+
+/**
+ * Format JSON using FracturedJson formatting with default options.
+ *
+ * FracturedJson produces human-readable yet compact output by intelligently
+ * choosing between inline, compact multiline, table, and expanded layouts.
+ *
+ *   dom::parser parser;
+ *   element doc = parser.parse(json_string);
+ *   cout << fractured_json(doc) << endl;
+ */
+template <class T>
+std::string fractured_json(T x);
+
+/**
+ * Format JSON using FracturedJson formatting with custom options.
+ *
+ *   dom::parser parser;
+ *   element doc = parser.parse(json_string);
+ *   fractured_json_options opts;
+ *   opts.max_total_line_length = 80;
+ *   cout << fractured_json(doc, opts) << endl;
+ */
+template <class T>
+std::string fractured_json(T x, const fractured_json_options& options);
+
+#if SIMDJSON_EXCEPTIONS
+template <class T>
+std::string fractured_json(simdjson_result<T> x);
+
+template <class T>
+std::string fractured_json(simdjson_result<T> x, const fractured_json_options& options);
+#endif
+
+/**
+ * Format a JSON string using FracturedJson formatting.
+ *
+ * This is useful for formatting output from the builder/static reflection API
+ * or any valid JSON string.
+ *
+ *   // With static reflection
+ *   MyStruct data = {...};
+ *   auto minified = simdjson::to_json_string(data);
+ *   auto formatted = simdjson::fractured_json_string(minified.value());
+ *
+ *   // Or with any JSON string
+ *   std::string json = R"({"key":"value"})";
+ *   auto formatted = simdjson::fractured_json_string(json);
+ */
+inline std::string fractured_json_string(std::string_view json_str);
+
+/**
+ * Format a JSON string using FracturedJson formatting with custom options.
+ */
+inline std::string fractured_json_string(std::string_view json_str,
+                                          const fractured_json_options& options);
+
+} // namespace simdjson
+
+#endif // SIMDJSON_DOM_FRACTURED_JSON_H

include/simdjson/dom/object-inl.h

@@ -186,7 +186,7 @@ inline simdjson_result<std::vector<element>> object::at_path_with_wildcard(std::
   }
 
   if (i >= json_path.size() || (json_path[i] != '.' && json_path[i] != '[')) {
-    // expect json path to always start with $ but this isn't currently
+    // expect JSONPath expressions to always start with $ but this isn't currently
     // expected in jsonpathutil.h.
     return INVALID_JSON_POINTER;
   }

include/simdjson/dom/object.h

@@ -175,7 +175,7 @@ public:
   inline simdjson_result<element> at_pointer(std::string_view json_pointer) const noexcept;
 
   /**
-   * Recursive function which processes the json path of each child element
+   * Recursive function which processes the JSON path of each child element
    */
   inline void process_json_path_of_child_elements(std::vector<element>::iterator& current, std::vector<element>::iterator& end, const std::string_view& path_suffix, std::vector<element>& accumulator) const noexcept;
 
@@ -189,7 +189,7 @@ public:
    * JSONPath queries that trivially convertible to JSON Pointer queries: key
    * names and array indices.
    *
-   * https://datatracker.ietf.org/doc/html/draft-normington-jsonpath-00
+   * https://www.rfc-editor.org/rfc/rfc9535 (RFC 9535)
    *
    * @return The value associated with the given JSONPath expression, or:
    *         - INVALID_JSON_POINTER if the JSONPath to JSON Pointer conversion fails

include/simdjson/dom/parser.h

@@ -204,10 +204,7 @@ public:
    *
    * ### std::string references
    *
-   * If you pass a mutable std::string reference (std::string&), the parser will seek to extend
-   * its capacity to SIMDJSON_PADDING bytes beyond the end of the string.
-   *
-   * Whenever you pass an std::string reference, the parser will access the bytes beyond the end of
+   * Whenever you pass an std::string reference, the parser may 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.
@@ -239,7 +236,7 @@ public:
   /** @overload parse(const uint8_t *buf, size_t len, bool realloc_if_needed) */
   simdjson_inline simdjson_result<element> parse(const char *buf, size_t len, bool realloc_if_needed = true) & noexcept;
   simdjson_inline simdjson_result<element> parse(const char *buf, size_t len, bool realloc_if_needed = true) && =delete;
-  /** @overload parse(const uint8_t *buf, size_t len, bool realloc_if_needed) */
+  /** @overload parse(const std::string &) */
   simdjson_inline simdjson_result<element> parse(const std::string &s) & noexcept;
   simdjson_inline simdjson_result<element> parse(const std::string &s) && =delete;
   /** @overload parse(const uint8_t *buf, size_t len, bool realloc_if_needed) */

include/simdjson/error-inl.h

@@ -8,7 +8,7 @@
 namespace simdjson {
 
 inline bool is_fatal(error_code error) noexcept {
-  return error == TAPE_ERROR || error == INCOMPLETE_ARRAY_OR_OBJECT;
+  return error == TAPE_ERROR || error == INCOMPLETE_ARRAY_OR_OBJECT || error == OUT_OF_ORDER_ITERATION || error == DEPTH_ERROR;
 }
 
 namespace internal {

include/simdjson/error.h

@@ -265,6 +265,8 @@ struct simdjson_result_base : protected std::pair<T, error_code> {
    */
   simdjson_inline T&& value_unsafe() && noexcept;
 
+  using value_type = T;
+  using error_type = error_code;
 }; // struct simdjson_result_base
 
 } // namespace internal
@@ -376,6 +378,8 @@ struct simdjson_result : public internal::simdjson_result_base<T> {
    */
   simdjson_inline T&& value_unsafe() && noexcept;
 
+  using value_type = T;
+  using error_type = error_code;
 }; // struct simdjson_result
 
 #if SIMDJSON_EXCEPTIONS

include/simdjson/fallback/bitmanipulation.h

@@ -41,6 +41,19 @@ simdjson_inline int leading_zeroes(uint64_t input_num) {
 #endif// _MSC_VER
 }
 
+simdjson_inline int trailing_zeroes(uint64_t input_num) {
+#ifdef _MSC_VER
+  unsigned long trailing_zero = 0;
+  // Search the mask data from least significant bit (LSB)
+  // to most significant bit (MSB) for a set bit (1).
+  if (_BitScanForward64(&trailing_zero, input_num))
+    return (int)trailing_zero;
+  else    return 64;
+#else
+  return __builtin_ctzll(input_num);
+#endif// _MSC_VER
+}
+
 } // unnamed namespace
 } // namespace fallback
 } // namespace simdjson

include/simdjson/fallback/builder.h

@@ -0,0 +1,8 @@
+#ifndef SIMDJSON_FALLBACK_BUILDER_H
+#define SIMDJSON_FALLBACK_BUILDER_H
+
+#include "simdjson/fallback/begin.h"
+#include "simdjson/generic/builder/amalgamated.h"
+#include "simdjson/fallback/end.h"
+
+#endif // SIMDJSON_FALLBACK_BUILDER_H