WIP: bump DEFAULT_INITIAL_CAPACITY to 256KB

Most CITM/Twitter realloc cost was due to growing from 1024 in 7-9 doublings
to reach the actual output size. Bumping the initial capacity to 256KB means
Twitter (82KB) fits in one allocation and CITM (496KB) only needs 1 growth.

Measured (TRUE A/B, 7 alternating rounds in single docker, with all prior
follow-ups in this branch + this cap bump):
  CITM:    4358 -> 4924 MB/s  (+13.0%)  - now ~2.3% AHEAD of Glaze
  Twitter: 6338 -> 8034 MB/s  (+26.8%)  - ~50% AHEAD of Glaze

Trade-off: 256KB upfront per string_builder instance. Reasonable for
high-perf JSON serialization but wasteful for tiny one-off messages.
Users serializing small payloads should pass a smaller initial_capacity
to the constructor.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

.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**
@@ -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/macos.yml

@@ -42,3 +42,14 @@ jobs:
           echo -e '#include <simdjson.h>\nint main(int argc,char**argv) {simdjson::dom::parser parser;simdjson::dom::element tweets = parser.load(argv[1]); }' > tmp.cpp && c++ -Idestination/include -Ldestination/lib -std=c++17 -Wl,-rpath,destination/lib -o linkandrun tmp.cpp -lsimdjson && ./linkandrun jsonexamples/twitter.json &&
           cd ../tests/installation_tests/find &&
           mkdir buildshared && cd buildshared && cmake -DCMAKE_INSTALL_PREFIX:PATH=../../../buildshared/destination .. &&  cmake --build .
+      - name: Use cmake (parsing for NaN/Infinity enabled)
+        run: |
+          mkdir build_nan_inf &&
+          cd build_nan_inf &&
+          cmake  -DSIMDJSON_ENABLE_NAN_INF=ON -DSIMDJSON_GOOGLE_BENCHMARKS=ON -DSIMDJSON_DEVELOPER_MODE=ON -DBUILD_SHARED_LIBS=ON -DCMAKE_INSTALL_PREFIX:PATH=destination ..  &&
+          cmake --build .   &&
+          ctest --output-on-failure -LE explicitonly -j   &&
+          cmake --install . &&
+          echo -e '#include <simdjson.h>\nint main(int argc,char**argv) {simdjson::dom::parser parser;simdjson::dom::element tweets = parser.load(argv[1]); }' > tmp.cpp && c++ -Idestination/include -Ldestination/lib -std=c++17 -Wl,-rpath,destination/lib -o linkandrun tmp.cpp -lsimdjson && ./linkandrun jsonexamples/twitter.json &&
+          cd ../tests/installation_tests/find &&
+          mkdir build_nan_inf && cd build_nan_inf && cmake -DCMAKE_INSTALL_PREFIX:PATH=../../../build_nan_inf/destination .. &&  cmake --build .

.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]')
@@ -21,6 +21,13 @@ jobs:
           cmake -DSIMDJSON_SANITIZE=ON -DCMAKE_BUILD_TYPE=Debug -DSIMDJSON_GOOGLE_BENCHMARKS=OFF -DSIMDJSON_DEVELOPER_MODE=ON -DBUILD_SHARED_LIBS=OFF ..  &&
           cmake --build .   &&
           ctest --output-on-failure -LE explicitonly -j
+      - name: Use cmake with address sanitizer (Parsing of NaN/Infinity enabled)
+        run: |
+          mkdir builddebug_nan_inf &&
+          cd builddebug_nan_inf &&
+          cmake -DSIMDJSON_SANITIZE=ON -DCMAKE_BUILD_TYPE=Debug -DSIMDJSON_GOOGLE_BENCHMARKS=OFF -DSIMDJSON_DEVELOPER_MODE=ON -DBUILD_SHARED_LIBS=OFF -DSIMDJSON_ENABLE_NAN_INF=ON ..  &&
+          cmake --build .   &&
+          ctest --output-on-failure -LE explicitonly -j
   ubuntu-build-undefined-sanitizer:
     if: >-
       ! contains(toJSON(github.event.commits.*.message), '[skip ci]') &&
@@ -39,3 +46,10 @@ jobs:
           cmake -DSIMDJSON_SANITIZE_UNDEFINED=ON -DCMAKE_BUILD_TYPE=Debug -DSIMDJSON_GOOGLE_BENCHMARKS=OFF -DSIMDJSON_DEVELOPER_MODE=ON -DBUILD_SHARED_LIBS=OFF ..  &&
           cmake --build .   &&
           ctest --output-on-failure -LE explicitonly -j
+      - name: Use cmake with undefined sanitizer (Parsing of NaN/Infinity enabled)
+        run: |
+          mkdir builddebugundefsani_nan_inf &&
+          cd builddebugundefsani_nan_inf &&
+          cmake -DSIMDJSON_SANITIZE_UNDEFINED=ON -DCMAKE_BUILD_TYPE=Debug -DSIMDJSON_GOOGLE_BENCHMARKS=OFF -DSIMDJSON_DEVELOPER_MODE=ON -DBUILD_SHARED_LIBS=OFF -DSIMDJSON_ENABLE_NAN_INF=ON ..  &&
+          cmake --build .   &&
+          ctest --output-on-failure -LE explicitonly -j

.github/workflows/ubuntu24.yml

@@ -12,14 +12,15 @@ jobs:
         shared: [ON, OFF]
         cxx: [g++-13, clang++-16]
         sanitizer: [ON, OFF]
+        nan_inf: [ON, OFF]
         build_type: [RelWithDebInfo, Debug, Release]
     steps:
       - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
       - name: Prepare
-        run: cmake -DCMAKE_BUILD_TYPE=${{matrix.build_type}} -DSIMDJSON_DEVELOPER_MODE=ON -DSIMDJSON_SANITIZE=${{matrix.sanitizer}} -DBUILD_SHARED_LIBS=${{matrix.shared}}  -B build
+        run: cmake -DCMAKE_BUILD_TYPE=${{matrix.build_type}} -DSIMDJSON_DEVELOPER_MODE=ON -DSIMDJSON_SANITIZE=${{matrix.sanitizer}} -DBUILD_SHARED_LIBS=${{matrix.shared}} -DSIMDJSON_ENABLE_NAN_INF=${{matrix.nan_inf}} -B build
         env:
           CXX: ${{matrix.cxx}}
       - name: Build
         run: cmake --build build -j=2
       - name: Test
-        run: ctest --output-on-failure --test-dir build
+        run: ctest --output-on-failure --test-dir build

.github/workflows/vs17-ci.yml

@@ -13,18 +13,22 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          - {gen: Visual Studio 17 2022, arch: Win32, shared: ON, build_type: Release}
-          - {gen: Visual Studio 17 2022, arch: Win32, shared: OFF, build_type: Release}
-          - {gen: Visual Studio 17 2022, arch: x64, shared: ON, build_type: Release}
-          - {gen: Visual Studio 17 2022, arch: x64, shared: OFF, build_type: Debug}
-          - {gen: Visual Studio 17 2022, arch: x64, shared: OFF, build_type: Release}
-          - {gen: Visual Studio 17 2022, arch: x64, shared: OFF, build_type: RelWithDebInfo}
+          - {gen: Visual Studio 17 2022, arch: Win32, shared: ON, build_type: Release, memory_map: OFF, nan_inf: OFF}
+          - {gen: Visual Studio 17 2022, arch: Win32, shared: OFF, build_type: Release, memory_map: OFF, nan_inf: OFF}
+          - {gen: Visual Studio 17 2022, arch: x64, shared: ON, build_type: Release, memory_map: OFF, nan_inf: OFF}
+          - {gen: Visual Studio 17 2022, arch: x64, shared: OFF, build_type: Debug, memory_map: OFF, nan_inf: OFF}
+          - {gen: Visual Studio 17 2022, arch: x64, shared: OFF, build_type: Release, memory_map: OFF, nan_inf: OFF}
+          - {gen: Visual Studio 17 2022, arch: x64, shared: OFF, build_type: RelWithDebInfo, memory_map: OFF, nan_inf: OFF}
+          - {gen: Visual Studio 17 2022, arch: x64, shared: OFF, build_type: Debug, memory_map: OFF, nan_inf: ON}
+          - {gen: Visual Studio 17 2022, arch: x64, shared: OFF, build_type: Release, memory_map: OFF, nan_inf: ON}
+          # Exercise the opt-in Windows memory-file mapping path at least once in CI.
+          - {gen: Visual Studio 17 2022, arch: x64, shared: OFF, build_type: Release, memory_map: ON, nan_inf: OFF}
     steps:
     - name: checkout
       uses: actions/checkout@v4
     - name: Configure
       run: |
-        cmake -G "${{matrix.gen}}" -A ${{matrix.arch}} -DSIMDJSON_DEVELOPER_MODE=ON -DSIMDJSON_COMPETITION=OFF -DBUILD_SHARED_LIBS=${{matrix.shared}} -B build
+        cmake -G "${{matrix.gen}}" -A ${{matrix.arch}} -DSIMDJSON_DEVELOPER_MODE=ON -DSIMDJSON_COMPETITION=OFF -DBUILD_SHARED_LIBS=${{matrix.shared}} -DSIMDJSON_ENABLE_MEMORY_FILE_MAPPING_ON_WINDOWS=${{matrix.memory_map}} -DSIMDJSON_ENABLE_NAN_INF=${{matrix.nan_inf}} -B build
     - name: Build Debug
       run: cmake --build build --config ${{matrix.build_type}} --verbose
     - name: Run tests
@@ -37,4 +41,4 @@ jobs:
     - name: Test Installation
       run: |
         cmake -G "${{matrix.gen}}" -A ${{matrix.arch}}  -B build_install_test tests/installation_tests/find
-        cmake --build build_install_test --config ${{matrix.build_type}}
+        cmake --build build_install_test --config ${{matrix.build_type}}

.gitignore

@@ -9,14 +9,6 @@
 # vim temp files
 .*.swp
 
-# Build directories
-build/
-build_*/
-buildreflect/
-
-# Ablation study results
-ablation/results/
-
 # XCode
 ^build/
 *.pbxuser
@@ -115,18 +107,3 @@ objs
 
 # clangd
 .cache
-
-# Ablation study results
-ablation/results/*.csv
-ablation/results/*.txt
-
-# Unified benchmark binary
-benchmark/unified_benchmark
-
-# Rust build artifacts
-*.rlib
-*.rmeta
-benchmark/static_reflect/serde-benchmark/target/
-**/target/debug/
-**/target/release/
-Cargo.lock

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)

BENCHMARK_METHODOLOGY.md

@@ -1,108 +0,0 @@
-# Benchmark Methodology
-
-## Overview
-This document describes the methodology used for the JSON parsing and serialization benchmarks.
-
-## Test Environment
-
-### Compiler and Flags
-- **Compiler**: Clang 21.0.0 with C++26 support
-- **Optimization**: `-O3 -march=native`
-- **Reflection Support**: `-freflection -fexpansion-statements -stdlib=libc++`
-- **Build System**: CMake with unified benchmark executable
-
-### Hardware
-Tests were run on Linux (aarch64) with results measured in MB/s throughput.
-
-## Datasets
-
-### Twitter Dataset
-- **File**: `jsonexamples/twitter.json`
-- **Size**: 631,515 bytes
-- **Content**: Array of tweet objects with nested user information
-- **Characteristics**: String-heavy (92%), moderate integer content (15%), minimal floats (<0.05%)
-
-### CITM Catalog Dataset
-- **File**: `jsonexamples/citm_catalog.json`
-- **Size**: 1,727,204 bytes
-- **Content**: Event catalog with performances, venues, and pricing
-- **Characteristics**: Complex nested structure with maps and arrays
-
-## Benchmark Design
-
-### Iterations
-- **Twitter**: 1,000 iterations per benchmark
-- **CITM**: 500 iterations per benchmark
-- **Warmup**: 10% of main iterations (100 for Twitter, 50 for CITM)
-
-### Memory Management
-- **String Builder Reuse**: Serialization benchmarks reuse the same string_builder instance across iterations
-- **Parser Instance**: Each parsing iteration uses a fresh parser instance for realistic performance
-- **Buffer Clearing**: Buffers are cleared (not deallocated) between iterations to maintain capacity
-
-### Timing Methodology
-1. Warmup phase to stabilize caches and branch predictors
-2. Timed phase measures wall clock time for all iterations
-3. Throughput calculated as: `(data_size * iterations) / total_time`
-4. Results reported in MB/s and microseconds per iteration
-
-## Libraries and Versions
-
-### Core Libraries
-- **simdjson**: Latest with C++26 reflection support
-- **nlohmann/json**: v3.11.2
-- **RapidJSON**: v1.1.0
-- **yyjson**: v0.8.0
-
-### Optional Libraries
-- **Serde (Rust)**: serde_json v1.0 via FFI (parsing and serialization)
-
-## Implementation Details
-
-### Parsing Benchmarks
-- All libraries perform full field extraction into C++ structures
-- No lazy evaluation or partial parsing
-- Validates that all expected fields are present
-
-### Serialization Benchmarks
-- Serializes complete C++ structures to JSON strings
-- Measures only the serialization time, not structure population
-- Output validation ensures correctness
-
-### simdjson Approaches
-
-#### Manual Parsing/Serialization
-- Hand-written code for each field
-- Explicit error checking
-- Maximum control over parsing/serialization order
-
-#### Reflection-Based
-- Uses C++26 static reflection
-- Automatic field discovery via `std::meta::nonstatic_data_members_of()`
-- Compile-time code generation for optimal performance
-
-#### simdjson::from() API
-- High-level convenient API
-- Type-safe automatic conversion
-- Parsing only (no serialization equivalent)
-
-## Running the Benchmarks
-
-### Parsing Benchmarks
-```bash
-./run_parsing_benchmarks.sh
-```
-
-### Serialization Benchmarks
-```bash
-./run_serialization_benchmarks.sh
-```
-
-Both scripts:
-1. Build the unified benchmark with all available libraries
-2. Compile with appropriate reflection flags
-3. Run benchmarks for both datasets
-4. Display results in tabular format
-
-## Reproducibility
-All benchmarks use deterministic iteration counts and can be reproduced by running the provided scripts. The unified benchmark executable ensures all libraries are tested under identical conditions.

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.2.3
+    VERSION 4.6.1
     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 "29.0.0" CACHE STRING "simdjson library version")
-set(SIMDJSON_LIB_SOVERSION "29" CACHE STRING "simdjson library soversion")
+set(SIMDJSON_LIB_VERSION "33.0.0" CACHE STRING "simdjson library version")
+set(SIMDJSON_LIB_SOVERSION "33" 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)
@@ -66,10 +75,48 @@ if(SIMDJSON_DEVELOPMENT_CHECKS)
   )
 endif()
 
+# padded_memory_map is always available on POSIX. On Windows it is disabled
+# by default because it depends on the `CreateFileMapping2` / `MapViewOfFile3`
+# APIs, which require Windows 10 version 1803 or later and are exported via
+# onecore.lib rather than the default kernel32.lib. Turn this option ON to
+# opt into the feature on Windows; simdjson will then set the appropriate
+# Windows version macros and link onecore, so everything that links
+# simdjson picks up both the compile-time declarations and the import
+# library automatically. The option is a no-op on POSIX (where the feature
+# is unconditionally enabled).
+option(SIMDJSON_ENABLE_MEMORY_FILE_MAPPING_ON_WINDOWS
+  "Enable simdjson::padded_memory_map on Windows (requires Windows 10 \
+version 1803 or later). Always enabled on POSIX." OFF)
+if(SIMDJSON_ENABLE_MEMORY_FILE_MAPPING_ON_WINDOWS)
+  simdjson_add_props(
+      target_compile_definitions PUBLIC
+      SIMDJSON_ENABLE_MEMORY_FILE_MAPPING_ON_WINDOWS=1
+  )
+  if(WIN32)
+    # Raise the Windows version floor so that <windows.h> declares the
+    # modern memory-mapping APIs, and link the import library that
+    # actually exports them. _WIN32_WINNT / WINVER / NTDDI_VERSION together
+    # tell <sdkddkver.h> which APIs to light up.
+    simdjson_add_props(
+        target_compile_definitions PUBLIC
+        _WIN32_WINNT=0x0A00
+        WINVER=0x0A00
+        NTDDI_VERSION=0x0A000006 # NTDDI_WIN10_RS5, Windows 10 version 1809
+    )
+    simdjson_add_props(
+        target_link_libraries PUBLIC
+        onecore
+    )
+  endif()
+endif()
+
 if(is_top_project)
+  option(SIMDJSON_INSTALL "Enable target install" ON)
   option(SIMDJSON_DEVELOPER_MODE "Enable targets for developing simdjson" OFF)
   option(BUILD_SHARED_LIBS "Build simdjson as a shared library" OFF)
   option(SIMDJSON_SINGLEHEADER "Disable singleheader generation" ON)
+else()
+  option(SIMDJSON_INSTALL "Enable target install" ${BUILD_SHARED_LIBS})
 endif()
 
 include(cmake/handle-deprecations.cmake)
@@ -83,10 +130,45 @@ add_library(simdjson ${SIMDJSON_SOURCES})
 add_library(simdjson::simdjson ALIAS simdjson)
 set(SIMDJSON_LIBRARIES simdjson)
 
+# Check for <bit> header compatibility
+include(CheckIncludeFileCXX)
+check_include_file_cxx(bit SIMDJSON_HAS_BIT_HEADER)
+
+# Enable precompiled headers for faster builds
+if(CMAKE_VERSION VERSION_GREATER_EQUAL "3.16")
+  set(SIMDJSON_PRECOMPILE_HEADERS
+    <algorithm>
+    <array>
+    <atomic>
+    <cassert>
+    <cctype>
+    <cerrno>
+    <cstddef>
+    <cstdint>
+    <cstdlib>
+    <cstring>
+    <memory>
+    <string>
+    <utility>
+    <vector>
+  )
+
+  if(SIMDJSON_HAS_BIT_HEADER)
+    list(APPEND SIMDJSON_PRECOMPILE_HEADERS <bit>)
+  endif()
+
+  target_precompile_headers(simdjson PRIVATE ${SIMDJSON_PRECOMPILE_HEADERS})
+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,13 +194,45 @@ 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)
+
+
+  if(CMAKE_CXX_COMPILER_ID STREQUAL "Clang" AND CMAKE_CXX_COMPILER_VERSION MATCHES "^21")
+    execute_process(
+        COMMAND ${CMAKE_CXX_COMPILER} --version
+        OUTPUT_VARIABLE CLANG_VERSION_OUTPUT
+        ERROR_VARIABLE CLANG_VERSION_ERROR
+        RESULT_VARIABLE CLANG_VERSION_RESULT
+    )
+    if(CLANG_VERSION_RESULT EQUAL 0 AND CLANG_VERSION_OUTPUT MATCHES "https://github.com/bloomberg/clang-p2996.git")
+        set(IS_BLOOMBERG_P2996_CLANG ON)
+        message(STATUS "Using Bloomberg P2996 Clang fork")
+    endif()
+  endif()
+
   # We would like to require C++26, but no compiler supports that!
   # This is a hack:
+  if(IS_BLOOMBERG_P2996_CLANG)
   simdjson_add_props(
       target_compile_options PUBLIC
       -freflection -fexpansion-statements -stdlib=libc++ -std=c++26
   )
+  else()
+  simdjson_add_props(
+      target_compile_options PUBLIC
+      -freflection -std=c++26
+  )
+  endif()
 else()
   simdjson_add_props(target_compile_features PUBLIC cxx_std_11)
 endif()
@@ -140,22 +254,10 @@ 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()
+option(SIMDJSON_ENABLE_NAN_INF "Allow parsing of NaN and Infinity JSON values" OFF)
+if(SIMDJSON_ENABLE_NAN_INF)
+  message(STATUS "simdjson NaN and Infinity parsing is enabled.")
+  simdjson_add_props(target_compile_definitions PUBLIC SIMDJSON_ENABLE_NAN_INF=1)
 endif()
 
 # GCC and Clang have horrendous Debug builds when using SIMD.
@@ -171,7 +273,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)
@@ -186,87 +293,89 @@ endif()
 
 # ---- Install rules ----
 
-include(CMakePackageConfigHelpers)
-include(GNUInstallDirs)
+if(SIMDJSON_INSTALL)
+    include(CMakePackageConfigHelpers)
+    include(GNUInstallDirs)
 
-if(SIMDJSON_SINGLEHEADER)
-  install(
-      FILES singleheader/simdjson.h
-      DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}"
-      COMPONENT simdjson_Development
-  )
+    if(SIMDJSON_SINGLEHEADER)
+      install(
+          FILES singleheader/simdjson.h
+          DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}"
+          COMPONENT simdjson_Development
+      )
+    endif()
+
+    install(
+        TARGETS simdjson
+        EXPORT simdjsonTargets
+        RUNTIME COMPONENT simdjson_Runtime
+        LIBRARY COMPONENT simdjson_Runtime
+        NAMELINK_COMPONENT simdjson_Development
+        ARCHIVE COMPONENT simdjson_Development
+        INCLUDES DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}"
+    )
+    configure_file(cmake/simdjson-config.cmake.in simdjson-config.cmake @ONLY)
+
+    write_basic_package_version_file(
+        simdjson-config-version.cmake
+        COMPATIBILITY SameMinorVersion
+    )
+
+    set(
+        SIMDJSON_INSTALL_CMAKEDIR "${CMAKE_INSTALL_LIBDIR}/cmake/simdjson"
+        CACHE STRING "CMake package config location relative to the install prefix"
+    )
+    mark_as_advanced(SIMDJSON_INSTALL_CMAKEDIR)
+
+    install(
+        FILES
+        "${PROJECT_BINARY_DIR}/simdjson-config.cmake"
+        "${PROJECT_BINARY_DIR}/simdjson-config-version.cmake"
+        DESTINATION "${SIMDJSON_INSTALL_CMAKEDIR}"
+        COMPONENT simdjson_Development
+    )
+
+    install(
+        EXPORT simdjsonTargets
+        NAMESPACE simdjson::
+        DESTINATION "${SIMDJSON_INSTALL_CMAKEDIR}"
+        COMPONENT simdjson_Development
+    )
+
+    if(SIMDJSON_BUILD_STATIC_LIB)
+      install(
+          TARGETS simdjson_static
+          EXPORT simdjson_staticTargets
+          ARCHIVE COMPONENT simdjson_Development
+          INCLUDES DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}"
+      )
+      install(
+          EXPORT simdjson_staticTargets
+          NAMESPACE simdjson::
+          DESTINATION "${SIMDJSON_INSTALL_CMAKEDIR}"
+          COMPONENT simdjson_Development
+      )
+    endif()
+
+    # pkg-config
+    include(cmake/JoinPaths.cmake)
+    join_paths(PKGCONFIG_INCLUDEDIR "\${prefix}" "${CMAKE_INSTALL_INCLUDEDIR}")
+    join_paths(PKGCONFIG_LIBDIR "\${prefix}" "${CMAKE_INSTALL_LIBDIR}")
+
+    if(SIMDJSON_ENABLE_THREADS)
+      set(PKGCONFIG_CFLAGS "-DSIMDJSON_THREADS_ENABLED=1")
+      if(CMAKE_THREAD_LIBS_INIT)
+        set(PKGCONFIG_LIBS_PRIVATE "Libs.private: ${CMAKE_THREAD_LIBS_INIT}")
+      endif()
+    endif()
+
+    configure_file("simdjson.pc.in" "simdjson.pc" @ONLY)
+    install(
+        FILES "${CMAKE_CURRENT_BINARY_DIR}/simdjson.pc"
+        DESTINATION "${CMAKE_INSTALL_LIBDIR}/pkgconfig"
+    )
 endif()
 
-install(
-    TARGETS simdjson
-    EXPORT simdjsonTargets
-    RUNTIME COMPONENT simdjson_Runtime
-    LIBRARY COMPONENT simdjson_Runtime
-    NAMELINK_COMPONENT simdjson_Development
-    ARCHIVE COMPONENT simdjson_Development
-    INCLUDES DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}"
-)
-configure_file(cmake/simdjson-config.cmake.in simdjson-config.cmake @ONLY)
-
-write_basic_package_version_file(
-    simdjson-config-version.cmake
-    COMPATIBILITY SameMinorVersion
-)
-
-set(
-    SIMDJSON_INSTALL_CMAKEDIR "${CMAKE_INSTALL_LIBDIR}/cmake/simdjson"
-    CACHE STRING "CMake package config location relative to the install prefix"
-)
-mark_as_advanced(SIMDJSON_INSTALL_CMAKEDIR)
-
-install(
-    FILES
-    "${PROJECT_BINARY_DIR}/simdjson-config.cmake"
-    "${PROJECT_BINARY_DIR}/simdjson-config-version.cmake"
-    DESTINATION "${SIMDJSON_INSTALL_CMAKEDIR}"
-    COMPONENT simdjson_Development
-)
-
-install(
-    EXPORT simdjsonTargets
-    NAMESPACE simdjson::
-    DESTINATION "${SIMDJSON_INSTALL_CMAKEDIR}"
-    COMPONENT simdjson_Development
-)
-
-if(SIMDJSON_BUILD_STATIC_LIB)
-  install(
-      TARGETS simdjson_static
-      EXPORT simdjson_staticTargets
-      ARCHIVE COMPONENT simdjson_Development
-      INCLUDES DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}"
-  )
-  install(
-      EXPORT simdjson_staticTargets
-      NAMESPACE simdjson::
-      DESTINATION "${SIMDJSON_INSTALL_CMAKEDIR}"
-      COMPONENT simdjson_Development
-  )
-endif()
-
-# pkg-config
-include(cmake/JoinPaths.cmake)
-join_paths(PKGCONFIG_INCLUDEDIR "\${prefix}" "${CMAKE_INSTALL_INCLUDEDIR}")
-join_paths(PKGCONFIG_LIBDIR "\${prefix}" "${CMAKE_INSTALL_LIBDIR}")
-
-if(SIMDJSON_ENABLE_THREADS)
-  set(PKGCONFIG_CFLAGS "-DSIMDJSON_THREADS_ENABLED=1")
-  if(CMAKE_THREAD_LIBS_INIT)
-    set(PKGCONFIG_LIBS_PRIVATE "Libs.private: ${CMAKE_THREAD_LIBS_INIT}")
-  endif()
-endif()
-
-configure_file("simdjson.pc.in" "simdjson.pc" @ONLY)
-install(
-    FILES "${CMAKE_CURRENT_BINARY_DIR}/simdjson.pc"
-    DESTINATION "${CMAKE_INSTALL_LIBDIR}/pkgconfig"
-)
-
 #
 # CPack
 #
@@ -343,18 +452,25 @@ add_subdirectory(fuzz)
 #
 # Source files should be just ASCII
 #
-find_program(FIND find)
-find_program(FILE file)
-find_program(GREP grep)
-if(FIND AND FILE AND GREP)
+find_program(FIND_CMD find)
+find_program(FILE_CMD file)
+find_program(GREP_CMD grep)
+if(FIND_CMD AND FILE_CMD AND GREP_CMD)
   add_test(
       NAME just_ascii
       COMMAND sh -c "\
-${FIND} include src windows tools singleheader tests examples benchmark \
--path benchmark/checkperf-reference -prune -name '*.h' -o -name '*.cpp' \
--type f -exec ${FILE} '{}' \; | ${GREP} -qv ASCII || exit 0  && exit 1"
+non_ascii=$(${FIND_CMD} include src windows tools singleheader tests examples benchmark \
+  -path benchmark/checkperf-reference -prune -name '*.h' -o -name '*.cpp' \
+  -type f -exec ${FILE_CMD} '{}' \; | ${GREP_CMD} -v ASCII); \
+if [ -n \"$non_ascii\" ]; then \
+  echo 'The following files contain non-ASCII characters:'; \
+  echo \"$non_ascii\"; \
+  exit 1; \
+fi"
       WORKING_DIRECTORY "${PROJECT_SOURCE_DIR}"
   )
+else()
+  message(WARNING "just_ascii test disabled because required tools were not found: find='${FIND_CMD}', file='${FILE_CMD}', grep='${GREP_CMD}'")
 endif()
 
 ##

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.2.3"
+PROJECT_NUMBER         = "4.6.1"
 
 # 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

FINAL_CHANGES_SUMMARY.md

@@ -1,53 +0,0 @@
-# Final Changes Summary
-
-## Clean Repository State Achieved ✓
-
-### Ablation Study (`ablation/`)
-- **run_ablation_study.sh** - Main ablation script that tests all optimization variants
-- **citm_serialization_test.cpp** - CITM test program for ablation
-- **ABLATION_RESULTS.md** - Documentation of expected results and methodology
-
-### Unified Benchmark (`benchmark/`)
-- **unified_benchmark.cpp** - Complete benchmark comparing simdjson vs other libraries
-- **build_unified_benchmark.sh** - Build script with automatic library detection
-- **UNIFIED_BENCHMARK_RESULTS.md** - Documentation of benchmark results
-
-### Updated Files
-- **.gitignore** - Added rules to exclude CSV results and benchmark binary
-
-### Removed Files
-- All temporary scripts (ablation_study_*.sh, run_*.sh)
-- All test files (citm_ablation_test.cpp, citm_ablation_simple.cpp)
-- Old results directory (ablation_results/)
-- citm_issue.md (no longer relevant)
-
-## How to Use
-
-### Run Unified Benchmark
-```bash
-cd /path/to/simdjson
-./benchmark/build_unified_benchmark.sh
-./benchmark/unified_benchmark
-```
-
-### Run Ablation Study
-```bash
-cd /path/to/simdjson
-./ablation/run_ablation_study.sh
-# Or with compilation time analysis:
-./ablation/run_ablation_study.sh --enable_compilation
-```
-
-## What Each Does
-
-**Unified Benchmark**: Compares simdjson (manual, reflection, from()) against nlohmann/json and RapidJSON using full Twitter and CITM datasets.
-
-**Ablation Study**: Measures the impact of individual optimizations (consteval, SIMD, fast digits, etc.) by disabling them one at a time.
-
-## Results Storage
-
-- Ablation results go to `ablation/results/` (gitignored)
-- Benchmark results are displayed on console
-- Documentation files contain expected/typical results
-
-This is now ready to push to the repository!

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:

PARSING_BENCHMARK_RESULTS.md

@@ -1,84 +0,0 @@
-# JSON Parsing Benchmark Results
-
-## Executive Summary
-Comprehensive benchmarks comparing JSON parsing performance across multiple libraries using two real-world datasets.
-
-## Test Environment
-- **Date**: September 2025
-- **Compiler**: Clang 21.0.0 with C++26 support
-- **Platform**: Linux (aarch64 and x64)
-- **Optimization**: `-O3`
-- **Datasets**: Twitter (631KB), CITM Catalog (1.7MB)
-- **Reflection**: Using C++26 static reflection (P2996) with consteval optimization
-
-
-**Hardware remarks**: The Intel Ice Lake processor has powerful SIMD support (AVX-512, two 512-bit execution units). The Apple processor runs at higher frequency and cna retire more instructions per cycle, while having weaker SIMD support (ARM NEON, four 128-bit execution units).
-
-## Twitter Dataset Results (631KB)
-### Intel Ice Lake
-| Library/Method | Throughput | Time/iter | Notes |
-|----------------|------------|-----------|-------|
-| **simdjson::from()** | 3.90 GB/s | 154.59 μs  | High-level API, uses C++26 reflection |
-| **simdjson (reflection)** | 3.75 GB/s | 160.60 μs | C++26 static reflection |
-| **simdjson (manual)** | 2.67 GB/s | 225.82 μs | Hand-written parsing code |
-| **yyjson** | 1.82 GB/s | 330.94 μs  | C library |
-| **Serde (Rust)** | 1.09 GB/s | 551.83 μs    | Via FFI |
-| **RapidJSON** | 387 MB/s | 1557.00 μs  | Full extraction |
-| **nlohmann/json** | 117 MB/s | 5346.73 μs  | Full extraction |
-
-### Apple Silicon
-| Library/Method | Throughput | Time/iter | Notes |
-|----------------|------------|-----------|-------|
-| **simdjson (manual)** | 4.36 GB/s | 138.04 μs | Hand-written parsing code |
-| **simdjson::from()** | 4.17 GB/s | 144.45 μs | High-level API, uses C++26 reflection |
-| **simdjson (reflection)** | 4.09 GB/s | 147.19 μs | C++26 static reflection |
-| **yyjson** | 2.23 GB/s | 269.71 μs | C library |
-| **Serde (Rust)** | 1.72 GB/s | 349.75 μs | Via FFI |
-| **RapidJSON** | 658 MB/s | 915.14 μs | Full extraction |
-| **nlohmann/json** | 172 MB/s | 3501.02 μs | Full extraction |
-
-## CITM Catalog Results (1.7MB)
-### Intel Ice Lake
-
-| Library/Method | Throughput | Time/iter | Notes |
-|----------------|------------|-----------|-------|
-| **simdjson (manual)** | 2.32 GB/s | 709.51 μs  | Manual parsing |
-| **simdjson (reflection)** | 1.85 GB/s | 890.34 μs  | C++26 static reflection |
-| **simdjson::from()** | 1.76 GB/s | 890.34 μs | Convenient API, uses C++26 reflection |
-| **yyjson** | 1.46 GB/s | 1130.75 μs | Full extraction |
-| **RapidJSON** | 552 GB/s | 2986.10 μs | Full extraction |
-| **Serde (Rust)** | 279 MB/s | 5903.36 μs  | Cross-language overhead |
-| **nlohmann/json** | 107187 MB/s |  15378.63 μs  | Full extraction |
-
-### Apple Silicon
-
-| Library/Method | Throughput | Time/iter | Notes |
-|----------------|------------|-----------|-------|
-| **simdjson (manual)** | 3.01 GB/s | 546.57 μs | Manual parsing |
-| **yyjson** | 2.68 GB/s | 614.32 μs | Full extraction |
-| **simdjson::from()** | 2.67 GB/s | 617.03 μs | Convenient API, uses C++26 reflection |
-| **simdjson (reflection)** | 2.66 GB/s | 620.07 μs | C++26 static reflection |
-| **RapidJSON** | 1.22 GB/s | 1354.62 μs | Full extraction |
-| **Serde (Rust)** | 535 MB/s | 3081.24 μs | Cross-language overhead |
-| **nlohmann/json** | 186 MB/s | 8874.02 μs | Full extraction |
-
-## Key Findings
-
-
-### Performance Leaders
-- On Apple Silicon, **simdjson (manual)** tops both datasets: 4.36 GB/s for Twitter and 3.01 GB/s for CITM.
-- On Intel Ice Lake, **simdjson::from()** leads Twitter at 3.90 GB/s, while **simdjson (manual)** leads CITM at 2.32 GB/s.
-- simdjson variants consistently dominate the top positions across platforms and datasets, with yyjson as a strong contender especially on Apple Silicon for CITM (2.68 GB/s, nearly matching simdjson::from() at 2.67 GB/s).
-
-
-### Technology Insights
-1. **C++26 Reflection**: simdjson's reflection approach shows variability by platform and dataset, achieving 140% of manual performance on Intel for Twitter (3.75 GB/s vs. 2.67 GB/s) and 94% on Apple Silicon (4.09 GB/s vs. 4.36 GB/s), averaging about 111%; for CITM, it reaches 80% on Intel (1.85 GB/s vs. 2.32 GB/s) and 88% on Apple Silicon (2.66 GB/s vs. 3.01 GB/s), averaging 84%.
-2. **Native Performance**: C/C++ libraries (simdjson, yyjson, RapidJSON, nlohmann/json) significantly outperform Rust's Serde, whichranks near the bottom in all cases.
-3. **API Trade-offs**: High-level APIs like simdjson::from() incur minimal overhead, often matching or exceeding reflection and manual methods (e.g., leading on Intel Twitter with 3.90 GB/s).
-4. **Fair Comparison**: All libraries now extract complete data structures including nested objects
-
-## Methodology
-- 3000 iterations for Twitter and CITM dataset
-- Fresh parser instance per iteration (realistic usage)
-- Full field extraction (no lazy evaluation)
-- Warmup phase before timing

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,6 +64,8 @@ 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)
+- [SereneDB](https://github.com/serenedb/serenedb)
 
 
 If you are planning to use simdjson in a product, please work from one of our releases.
@@ -186,6 +189,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
 --------------
@@ -208,10 +212,31 @@ We have an in-depth paper focused on the UTF-8 validation:
 
 We also have an informal [blog post providing some background and context](https://branchfree.org/2019/02/25/paper-parsing-gigabytes-of-json-per-second/).
 
-For the video inclined, <br />
+For the video inclined, we had a talk at QCon San Francisco 2019<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.)
 
+We also had a CppCon 2025 talk. We show how C++26 reflection allows for one-line serialization (to_json(player)) or deserialization—without invasive macros or manual mapping—using nothing but the C++ standard library. Whether you’re a performance junkie or simply interested in the roadmap for the next decade of C++ development, watch our full talk!
+
+[![simdjson at CppCon 2025](http://img.youtube.com/vi/Mcgk3CxHYMs/0.jpg)](http://www.youtube.com/watch?v=Mcgk3CxHYMs)<br />
+
+
+
+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
 -------
 

SERIALIZATION_BENCHMARK_RESULTS.md

@@ -1,84 +0,0 @@
-# JSON Serialization Benchmark Results
-
-## Executive Summary
-Performance comparison of JSON serialization (C++ structs → JSON) across multiple libraries.
-
-## Test Environment
-- **Date**: September 2025
-- **Compiler**: Clang 21.0.0 with C++26 support
-- **Platform**: Linux (aarch64 and x64)
-- **Optimization**: `-O3` (we do not use `-march=native` or other flags)
-- **Datasets**: Twitter (631KB), CITM Catalog (1.7MB)
-- **Consteval**: Enabled with `std::define_static_string` for compile-time key generation
-
-**Software remarks**: The simdjson library makes little use of SIMD instructions when serializing.
-
-**Hardware remarks**: The Intel Ice Lake processor has powerful SIMD support (AVX-512, two 512-bit execution units). The Apple processor runs at higher frequency and cna retire more instructions per cycle, while having weaker SIMD support (ARM NEON, four 128-bit execution units).
-
-
-## Twitter Dataset Results (631KB)
-
-### Intel Ice Lake
-| Library/Method | Throughput | Time/iter | Notes |
-|----------------|------------|-----------|-------|
-| **simdjson (reflection)** | 3.48 GB/s | 23.24 μs | C++26 static reflection with consteval |
-| **yyjson** | 2.07 GB/s | 39.11 μs | C library |
-| **simdjson (DOM)** | 1.66 GB/s | 48.85 μs | Manual DOM serialization |
-| **Serde (Rust)** | 1.34 GB/s | 60.38 μs | Via FFI |
-| **RapidJSON** | 494 MB/s | 163.86 μs | DOM-based |
-| **nlohmann/json** | 243 MB/s | 333.51 μs | Slowest |
-
-### Apple Silicon
-| Library/Method | Throughput | Time/iter | Notes |
-|----------------|------------|-----------|-------|
-| **simdjson (reflection)** | 3.52 GB/s | 23.00 μs | C++26 static reflection with consteval |
-| **yyjson** | 2.08 GB/s | 38.94 μs | C library |
-| **simdjson (DOM)** | 1.67 GB/s | 48.36 μs | Manual DOM serialization |
-| **Serde (Rust)** | 1.32 GB/s | 61.28 μs | Via FFI |
-| **RapidJSON** | 861 MB/s | 94.04 μs | DOM-based |
-| **nlohmann/json** | 242 MB/s | 334.18 μs | Slowest |
-
-## CITM Catalog Results (1.7MB)
-
-### Intel Ice Lake
-| Library/Method | Throughput | Time/iter | Notes |
-|----------------|------------|-----------|-------|
-| **simdjson (reflection)** | 2.10 GB/s | 226.78 μs | Fastest with consteval optimization |
-| **yyjson** | 1.68 GB/s | 283.64 μs | C library |
-| **Serde (Rust)** | 1.16 GB/s | 411.79 μs | Strong performance |
-| **simdjson (DOM)** | 799 MB/s | 597.50 μs | Manual implementation |
-| **RapidJSON** | 571 MB/s | 835.23 μs | DOM-based |
-| **nlohmann/json** | 127 MB/s | 3747.76 μs | Slowest |
-
-### Apple Silicon
-| Library/Method | Throughput | Time/iter | Notes |
-|----------------|------------|-----------|-------|
-| **simdjson (reflection)** | 2.25 GB/s | 212.06 μs | Fastest with consteval optimization |
-| **yyjson** | 1.67 GB/s | 286.43 μs | C library |
-| **Serde (Rust)** | 1.17 GB/s | 408.82 μs | Strong performance |
-| **simdjson (DOM)** | 780 MB/s | 612.03 μs | Manual implementation |
-| **RapidJSON** | 354 MB/s | 1349.76 μs | DOM-based |
-| **nlohmann/json** | 125 MB/s | 3831.37 μs | Slowest |
-
-## Key Findings
-
-### Performance Leaders
-- **simdjson (reflection)**  leads across all tests, peaking at 3.52 GB/s on Twitter (Apple Silicon) and 2.25 GB/s on CITM (Apple Silicon), showcasing best-in-class serialization performance.
-- **yyjson** consistently ranks second, achieving 2.08 GB/s on Twitter (Apple Silicon) and 1.68 GB/s on CITM (Intel Ice Lake), competitive but trailing simdjson by 1.5-1.7x.
-- Traditional libraries (RapidJSON, nlohmann/json) lag significantly, with nlohmann/json being the slowest at 242-243 MB/s on Twitter and 125-127 MB/s on CITM, roughly 14-30x slower than simdjson (reflection).
-
-### Technology Insights
-
-1. **Consteval Impact**: Using `std::define_static_string` for compile-time JSON key generation significantly boosts performance, enabling simdjson (reflection) to achieve up to 3.52 GB/s on Twitter, a 1.7-2.1x improvement over non-consteval methods like yyjson.
-2. **Memory Management**: String builder reuse combined with consteval key generation optimizes memory allocation, contributing to simdjson (reflection)'s superior performance across datasets and platforms.
-3. **Platform Differences**: Apple Silicon slightly edges out Intel Ice Lake for simdjson (reflection) on both datasets (3.52 GB/s vs. 3.48 GB/s on Twitter, 2.25 GB/s vs. 2.10 GB/s on CITM), likely due to higher frequency and instruction retirement, despite weaker SIMD support (ARM NEON vs. AVX-512).
-4. **Serde (Rust)** trails C/C++ libraries by 1.8-3x.
-5. **Reflection Performance**: C++26 reflection with consteval outperforms all alternatives
-
-
-## Methodology
-- 3000 iterations for Twitter and CITM dataset
-- String builder reuse for simdjson (realistic optimization)
-- Full serialization with proper JSON escaping
-- Warmup phase before timing
-- Consteval optimization with `std::define_static_string`

ablation.md

@@ -1,497 +0,0 @@
-# Reflection-based Serialization Ablation Study
-
-This document tracks the performance impact of various optimizations in the reflection-based serialization implementation for simdjson.
-
-## Study Overview
-
-The ablation study isolates key performance components to understand their individual contribution to serialization performance. We test each variant against the Twitter benchmark dataset.
-
-## Test Environment
-
-- **Dataset**: Twitter JSON benchmark (`jsonexamples/twitter.json`)
-- **Benchmark**: `benchmark_serialization_twitter` (simdjson static reflection)
-- **Platform**: Linux x86_64 with SSE2/AVX support
-- **Compiler**: (to be determined during build)
-
-## Optimization Components Tested
-
-### 1. SIMD String Escaping
-**Location**: `json_string_builder-inl.h:87-142`
-- **SSE2**: Vectorized character checking using `_mm_loadu_si128`, `_mm_cmpeq_epi8`
-- **NEON**: ARM SIMD equivalent using `vld1q_u8`, `vceqq_u8`
-- **Impact**: Critical for string-heavy workloads like Twitter data
-
-### 2. Compile-time String Processing (Consteval)
-**Location**: `json_string_builder-inl.h:204-225`
-- **Feature**: Pre-computes escaped strings at compile time when `SIMDJSON_CONSTEVAL` is enabled
-- **Impact**: Reduces runtime escaping overhead for static strings
-
-### 3. Fast Digit Counting
-**Location**: `json_string_builder-inl.h:308-354`
-- **Feature**: Optimized integer-to-string conversion using bit manipulation
-- **Methods**: `fast_digit_count()` with logarithmic lookup tables
-
-### 4. Decimal Lookup Tables
-**Location**: `json_string_builder-inl.h:355-373`
-- **Feature**: Pre-computed decimal pairs for fast number serialization
-- **Impact**: Avoids repeated modulo/division operations
-
-### 5. Vectorized Number Serialization
-**Location**: `json_string_builder-inl.h:376-456`
-- **Feature**: Template specializations with optimized paths for different numeric types
-- **Impact**: Efficient conversion of various number formats
-
-## Ablation Variants
-
-### Baseline (Full Optimizations)
-- All optimizations enabled
-- SIMD string escaping: ✓
-- Consteval processing: ✓
-- Fast digit counting: ✓
-- Lookup tables: ✓
-- Vectorized serialization: ✓
-
-### Variant 1: No SIMD Escaping
-- Forces `simple_needs_escaping()` instead of `fast_needs_escaping()`
-- Disables SSE2/NEON vectorized character checking
-
-### Variant 2: No Consteval
-- Disables compile-time string processing
-- Forces runtime escaping for all strings
-
-### Variant 3: No Fast Digits
-- Replaces optimized digit counting with standard library methods
-- Uses `std::to_string()` for number conversion
-
-### Variant 4: No Lookup Tables
-- Removes decimal table optimization
-- Uses only modulo/division for digit extraction
-
-### Variant 5: Scalar Only
-- Disables all SIMD optimizations
-- Forces scalar-only code paths
-
-## Benchmark Results
-
-### Baseline (Full Optimizations) - CORRECTED
-```
-bench_simdjson_static_reflection                             :  2449.25 MB/s   0.63 Ms/s
-# output volume: 93311 bytes
-```
-
-**Note:** Initial baseline measurement of 416.69 MB/s was incorrect due to different build configuration.
-
-### Variant 1: No SIMD Escaping
-```
-bench_simdjson_static_reflection                             :  2380.46 MB/s   0.61 Ms/s
-# output volume: 93311 bytes
-Performance Impact: -2.8% throughput vs corrected baseline (2449.25 → 2380.46 MB/s)
-```
-
-### Variant 2: No Consteval
-```
-bench_simdjson_static_reflection                             :  1657.55 MB/s   0.43 Ms/s
-# output volume: 93311 bytes
-Performance Impact: -32.3% throughput vs baseline (2449.25 → 1657.55 MB/s)
-```
-
-### Variant 3: No Fast Digits
-```
-bench_simdjson_static_reflection                             :  3201.16 MB/s   0.82 Ms/s
-# output volume: 93311 bytes
-Performance Impact: +30.7% throughput vs baseline (2449.25 → 3201.16 MB/s)
-```
-
-**Unexpected Result:** This variant shows significant performance *improvement*, suggesting the `std::to_string()` fallback may be more optimized than the custom `fast_digit_count()` implementation on this platform/compiler combination.
-
-## Additional Performance-Critical Components Identified
-
-Beyond the core optimizations tested, several other performance-critical functions were identified for future ablation studies:
-
-### 1. **Buffer Growth Strategy**
-**Location**: `json_string_builder-inl.h:258-262`
-- **Current**: Exponential growth (`capacity * 2`)
-- **Alternative**: Linear growth with fixed increments
-- **Impact**: Memory allocation patterns affect serialization throughput
-
-### 2. **Branch Prediction Hints**
-**Location**: Throughout codebase using `simdjson_likely/unlikely`
-- **Current**: Uses `__builtin_expect` for hot path optimization
-- **Test**: Measure compiler's natural branch prediction effectiveness
-- **Impact**: Critical for tight loops in serialization
-
-### 3. **String Escaping Fast Path**
-**Location**: `json_string_builder-inl.h:184-191`
-- **Optimization**: `memcpy` fast path when no escaping needed
-- **Alternative**: Always use character-by-character processing
-- **Impact**: Significant for strings without special characters
-
-### 4. **Template Instantiation Overhead**
-**Location**: `json_builder.h` reflection expansion
-- **Current**: `[:expand:]` syntax with compile-time field iteration
-- **Alternative**: Manual field enumeration
-- **Impact**: Compilation time vs runtime performance tradeoff
-
-### 5. **Memory Allocation Strategy**
-**Location**: `string_builder` constructor and `grow_buffer`
-- **Current**: `std::nothrow` and `std::unique_ptr` with exponential growth
-- **Alternatives**: Custom allocators, different growth strategies
-- **Impact**: Memory fragmentation and allocation overhead
-
-## Micro-optimization Implementation Examples
-
-```cpp
-// Branch prediction hints ablation
-#ifdef SIMDJSON_ABLATION_NO_BRANCH_HINTS
-  if (upcoming_bytes <= capacity - position) return true;
-#else
-  if (simdjson_likely(upcoming_bytes <= capacity - position)) return true;
-#endif
-
-// Buffer growth strategy ablation
-#ifdef SIMDJSON_ABLATION_LINEAR_GROWTH
-  grow_buffer(position + upcoming_bytes + 1024); // Linear
-#else
-  grow_buffer((std::max)(capacity * 2, position + upcoming_bytes)); // Exponential
-#endif
-
-// Fast path ablation
-#ifdef SIMDJSON_ABLATION_NO_ESCAPE_FAST_PATH
-  // Always use slow path
-#else
-  if (!fast_needs_escaping(input)) {
-    memcpy(out, input.data(), input.size());
-    return input.size();
-  }
-#endif
-```
-
-### Variant 4: No Branch Prediction Hints
-```
-Status: IMPLEMENTED - Testing in progress
-```
-
-**Implementation**: Disables `simdjson_likely/unlikely` macros that use `__builtin_expect` for branch prediction hints.
-
-**Files Modified**: `json_string_builder-inl.h:240-256` (capacity_check function)
-
-**Expected Impact**: 2-8% performance change depending on branch prediction effectiveness. Modern CPUs have excellent branch predictors, so manual hints may have minimal impact.
-
-### Variant 5: Linear Buffer Growth
-```
-Status: IMPLEMENTED - Testing in progress
-```
-
-**Implementation**: Changes buffer growth from exponential (`capacity * 2`) to linear (`position + upcoming_bytes + 1024`).
-
-**Files Modified**: `json_string_builder-inl.h:258-262`
-
-**Expected Impact**: Could impact memory usage patterns and allocation frequency. Linear growth uses less memory but may trigger more allocations.
-
-### Variant 6: No String Escape Fast Path
-```
-Status: IMPLEMENTED - Testing in progress
-```
-
-**Implementation**: Forces character-by-character string processing, disabling the `memcpy` fast path for strings that don't need escaping.
-
-**Files Modified**: `json_string_builder-inl.h:184-191`
-
-**Expected Impact**: Significant performance degradation (10-25%) for datasets with many non-escaped strings, as it loses the fast path optimization.
-
-## Performance Analysis
-
-### Key Findings
-
-1. **Consteval Optimization is Critical**: Disabling compile-time string processing (`consteval_to_quoted_escaped`) results in a **32.3% performance degradation**. This is by far the largest negative impact measured.
-
-2. **SIMD String Escaping has Modest Impact**: Disabling vectorized string escaping shows only a **2.8% performance degradation**, suggesting that the Twitter dataset may not be string-escape-heavy enough to fully benefit from SIMD acceleration.
-
-3. **Fast Digit Counting is Counter-productive**: Surprisingly, disabling the custom `fast_digit_count()` optimization results in a **30.7% performance improvement**. This suggests that `std::to_string()` is more optimized than the custom implementation on this platform.
-
-### Performance Hierarchy (Impact on Twitter Benchmark)
-
-**Measured Results:**
-1. **Fast digit counting removal**: +30.7% (3201.16 vs 2449.25 MB/s) - *Performance improvement*
-2. **Consteval optimizations**: -32.3% (1657.55 vs 2449.25 MB/s) - *Critical degradation*
-3. **SIMD string escaping**: -2.8% (2380.46 vs 2449.25 MB/s) - *Minor degradation*
-
-**Additional Variants Implemented (Testing in Progress):**
-4. **Branch prediction hints**: Expected -2% to -8% impact
-5. **Linear vs exponential buffer growth**: Expected variable impact on memory-constrained scenarios
-6. **String escape fast path**: Expected -10% to -25% impact for non-escaped strings
-
-### Implications for Reflection-based Serialization
-
-1. **Compile-time computation is the killer feature**: The P2996 reflection implementation's strength lies in `consteval` field name processing, providing massive performance benefits over runtime computation.
-
-2. **Don't over-optimize numeric conversion**: Custom number serialization can sometimes be counterproductive compared to well-optimized standard library implementations.
-
-3. **SIMD has limited impact on reflection workloads**: Vector optimizations show modest gains, suggesting that reflection-based serialization is more bottlenecked by algorithmic complexity than instruction throughput.
-
-4. **Platform-specific optimization is crucial**: The unexpected performance gain from removing custom digit counting highlights the importance of benchmarking optimizations across different platforms and compiler versions.
-
-5. **Micro-optimizations form a third performance layer**: Beyond algorithmic (consteval) and instruction-level (SIMD) optimizations, micro-optimizations like branch hints, buffer growth strategies, and fast paths provide an additional 5-20% performance tuning opportunity.
-
-### Compilation Time vs Runtime Performance Trade-offs
-
-The consteval optimization demonstrates a classic trade-off:
-- **Increased compilation time**: Compile-time string processing adds overhead during build
-- **Significant runtime gains**: 32.3% performance improvement justifies the compilation cost
-- **Memory footprint**: Pre-computed strings may increase binary size but improve cache performance
-
-This pattern is characteristic of modern C++ optimization strategies where compile-time work pays dividends at runtime.
-
-### Compilation Time Impact Analysis
-
-While we measured significant runtime performance differences, compilation time also varies significantly:
-
-**Estimated Compilation Time Impact** (based on code complexity):
-- **Baseline**: Reference compilation time
-- **No Consteval**: ~15-25% faster compilation (less compile-time computation)
-- **No SIMD Escaping**: ~5-10% faster compilation (simpler code paths)
-- **No Fast Digits**: ~2-5% faster compilation (less template complexity)
-
-**Key Insight**: The consteval optimization that provides the biggest runtime benefit (+32.3%) likely has the highest compilation cost, representing a classic compile-time vs runtime performance trade-off that's central to modern C++ optimization philosophy.
-
-## Implementation Details
-
-### Build Configuration
-
-**Prerequisites:**
-- Experimental Clang with P2996 reflection support (clang version 21.0.0git from bloomberg/clang-p2996)
-- Rust compiler: `sudo apt-get install -y rustc cargo`
-- Google perftools: `sudo apt-get install -y libgoogle-perftools-dev`
-
-**Build Steps:**
-1. `mkdir build && cd build`
-2. `cmake -DCMAKE_CXX_COMPILER=clang++ -DSIMDJSON_DEVELOPER_MODE=ON -DSIMDJSON_STATIC_REFLECTION=ON -DBUILD_SHARED_LIBS=OFF -DSIMDJSON_ENABLE_RUST=ON ..`
-3. `cmake --build . --target benchmark_serialization_twitter`
-
-**Ablation Variants Implementation:**
-Each variant is implemented through preprocessor definitions:
-- `SIMDJSON_ABLATION_NO_SIMD_ESCAPING`: Disables SIMD string escaping
-- `SIMDJSON_ABLATION_NO_CONSTEVAL`: Disables consteval optimizations
-- `SIMDJSON_ABLATION_NO_FAST_DIGITS`: Disables fast digit counting
-- `SIMDJSON_ABLATION_NO_LOOKUP_TABLES`: Disables decimal lookup tables
-- `SIMDJSON_ABLATION_SCALAR_ONLY`: Disables all SIMD
-
-### Code Modifications
-
-#### Variant 1: No SIMD Escaping
-**File Modified:** `include/simdjson/generic/ondemand/json_string_builder-inl.h:86-146`
-**Change:** Added `#ifdef SIMDJSON_ABLATION_NO_SIMD_ESCAPING` guard to force `simple_needs_escaping()` instead of vectorized implementations.
-
-```cpp
-#ifdef SIMDJSON_ABLATION_NO_SIMD_ESCAPING
-simdjson_inline bool fast_needs_escaping(std::string_view view) {
-  return simple_needs_escaping(view);
-}
-#elif SIMDJSON_EXPERIMENTAL_HAS_NEON
-// ... original NEON implementation
-#elif SIMDJSON_EXPERIMENTAL_HAS_SSE2
-// ... original SSE2 implementation
-#else
-// ... original fallback
-#endif
-```
-
-**Impact:** Forces scalar character-by-character checking instead of 16-byte SIMD processing for string escaping detection.
-
-#### Variant 2: No Consteval
-**Files Modified:**
-- `include/simdjson/generic/ondemand/json_string_builder-inl.h:208-229`
-- `include/simdjson/generic/ondemand/json_builder.h:112,247`
-
-**Changes:**
-1. Added `!defined(SIMDJSON_ABLATION_NO_CONSTEVAL)` guard to consteval function definition
-2. Replaced compile-time `consteval_to_quoted_escaped()` calls with runtime string concatenation
-
-```cpp
-// In json_string_builder-inl.h
-#if SIMDJSON_CONSTEVAL && !defined(SIMDJSON_ABLATION_NO_CONSTEVAL)
-consteval std::string consteval_to_quoted_escaped(std::string_view input) {
-  // ... compile-time implementation
-}
-#endif
-
-// In json_builder.h
-#if SIMDJSON_CONSTEVAL && !defined(SIMDJSON_ABLATION_NO_CONSTEVAL)
-    constexpr auto key = std::define_static_string(consteval_to_quoted_escaped(std::meta::identifier_of(dm)));
-#else
-    std::string key = "\"" + std::string(std::meta::identifier_of(dm)) + "\"";
-#endif
-```
-
-**Impact:** Forces runtime string construction and escaping for field names instead of compile-time pre-computation, resulting in significant performance degradation (-32.3%).
-
-#### Variant 3: No Fast Digits
-**File Modified:** `include/simdjson/generic/ondemand/json_string_builder-inl.h:353-363`
-
-**Change:** Replaced optimized `fast_digit_count()` with standard library `std::to_string().length()`
-
-```cpp
-template <typename number_type, typename = typename std::enable_if<
-                                    std::is_unsigned<number_type>::value>::type>
-simdjson_inline size_t digit_count(number_type v) noexcept {
-#ifdef SIMDJSON_ABLATION_NO_FAST_DIGITS
-  // Fallback: use standard library conversion to count digits
-  return std::to_string(v).length();
-#else
-  return fast_digit_count(v);
-#endif
-}
-```
-
-**Impact:** **Unexpected performance improvement (+30.7%)** - demonstrates that custom optimizations can sometimes be counterproductive compared to highly-optimized standard library implementations on modern compilers.
-
-#### Variant 4: No Branch Prediction Hints
-**File Modified:** `include/simdjson/generic/ondemand/json_string_builder-inl.h:240-256`
-
-**Change:** Disables `__builtin_expect` branch prediction hints in critical capacity checking function
-
-```cpp
-#ifdef SIMDJSON_ABLATION_NO_BRANCH_HINTS
-  if (upcoming_bytes <= capacity - position) {
-    return true;
-  }
-  if (position + upcoming_bytes < position) {
-    return false;
-  }
-#else
-  if (simdjson_likely(upcoming_bytes <= capacity - position)) {
-    return true;
-  }
-  if (simdjson_likely(position + upcoming_bytes < position)) {
-    return false;
-  }
-#endif
-```
-
-**Expected Impact:** Modern CPUs have sophisticated branch predictors, so manual hints may provide only modest gains (2-8%).
-
-#### Variant 5: Linear Buffer Growth
-**File Modified:** `include/simdjson/generic/ondemand/json_string_builder-inl.h:258-262`
-
-**Change:** Replaces exponential buffer growth with linear growth strategy
-
-```cpp
-#ifdef SIMDJSON_ABLATION_LINEAR_GROWTH
-  grow_buffer(position + upcoming_bytes + 1024); // Linear growth
-#else
-  grow_buffer((std::max)(capacity * 2, position + upcoming_bytes)); // Exponential
-#endif
-```
-
-**Expected Impact:** Trade-off between memory usage (linear uses less) and allocation frequency (linear triggers more reallocations).
-
-#### Variant 6: No String Escape Fast Path
-**File Modified:** `include/simdjson/generic/ondemand/json_string_builder-inl.h:184-191`
-
-**Change:** Forces slow path for all string processing, disabling `memcpy` optimization
-
-```cpp
-#ifdef SIMDJSON_ABLATION_NO_ESCAPE_FAST_PATH
-  // Always use slow path - no fast path optimization
-#else
-  if (!fast_needs_escaping(input)) { // fast path!
-    memcpy(out, input.data(), input.size());
-    return input.size();
-  }
-#endif
-```
-
-**Expected Impact:** Significant degradation (10-25%) for strings without special characters, as it eliminates the bulk copy optimization.
-
-## Low-Hanging Fruit Optimizations Implemented
-
-Based on the ablation study results, several micro-optimizations have been implemented to further enhance performance:
-
-### 1. **Inline Function Optimizations** (`SIMDJSON_ABLATION_NO_INLINE_OPTIMIZATIONS`)
-**Implementation**: Manual inlining, improved branch predictions, and fast-path optimizations:
-- **escape_json_char()**: Manual loop unrolling for common quote/backslash cases
-- **capacity_check()**: Enhanced branch prediction with `simdjson_unlikely` for rare overflow path
-- **write_string_escaped()**: Optimized fast path detection with prefetching for large strings
-- **Buffer growth strategy**: Cache-line aligned allocation (64-byte boundaries) for better memory access
-
-**Expected Impact**: 5-15% performance improvement in string-heavy workloads like Twitter JSON
-
-### 2. **Memory Prefetching Optimizations** (`SIMDJSON_ABLATION_NO_PREFETCH`)
-**Implementation**: Strategic `__builtin_prefetch` usage in performance-critical loops:
-- **SIMD string scanning**: Prefetch next 64-byte cache line during 16-byte SIMD processing
-- **String escaping**: Prefetch destination memory for large string copies (>64 bytes)
-- **Control character lookup**: Prefetch next control character table entry during escaping
-
-**Expected Impact**: 3-8% performance improvement on large documents with good cache behavior
-
-### 3. **Constant Folding Optimizations** (`SIMDJSON_ABLATION_NO_CONSTANT_FOLDING`)
-**Implementation**: Enhanced compile-time computations to reduce runtime overhead:
-- **Field count pre-computation**: Compile-time calculation of struct field counts for better optimization
-- **Small enum optimization**: Fast compile-time switch generation for enums with ≤8 values
-- **Key size computation**: Pre-compute field name sizes for better buffer management
-- **Empty struct fast path**: Compile-time detection and fast path for structs with zero fields
-
-**Expected Impact**: 2-5% performance improvement through reduced template instantiation overhead
-
-### 4. **Combined Optimization Analysis**
-These micro-optimizations represent a **third performance layer** beyond the major algorithmic (consteval) and instruction-level (SIMD) optimizations:
-
-**Performance Hierarchy** (Updated):
-1. **Algorithmic layer** (consteval): ±32.3% impact - most critical
-2. **Instruction-level layer** (SIMD): ±2.8% impact - modest gains
-3. **Micro-optimization layer** (inline/prefetch/constant-folding): ±5-25% impact - fine-tuning
-
-## Summary
-
-This ablation study successfully identified the key performance drivers in simdjson's reflection-based serialization implementation. The study revealed that **compile-time optimizations significantly outweigh runtime SIMD optimizations** for this workload.
-
-### Key Takeaways for Presentation:
-
-1. **Three-Layer Performance Hierarchy Discovered**:
-   - **Algorithmic layer** (consteval): ±32.3% impact - most critical
-   - **Instruction-level layer** (SIMD): ±2.8% impact - modest gains
-   - **Micro-optimization layer** (branches, fast paths): ±5-25% impact - fine-tuning
-
-2. **Consteval dominates reflection performance**: 32.3% impact demonstrates that compile-time computation is the cornerstone of efficient C++26 reflection
-
-3. **Surprising counter-optimizations exist**: Custom "fast" digit counting actually hurt performance (+30.7% when removed), showing standard library superiority
-
-4. **Micro-optimizations matter for production code**: Branch hints, buffer strategies, and fast paths provide the final 5-25% performance layer
-
-5. **Platform-specific validation is essential**: Results vary significantly based on compiler optimizations and hardware characteristics
-
-### Reproducibility Notes:
-
-All measurements performed on:
-- **Compiler**: clang version 21.0.0git (bloomberg/clang-p2996)
-- **Platform**: Linux aarch64-unknown-linux-gnu
-- **Dataset**: jsonexamples/twitter.json (93,311 bytes)
-- **Build**: Release mode with -Og optimization
-
-### Build Instructions for Future Reference:
-
-```bash
-# Clean baseline
-mkdir build && cd build
-cmake -DCMAKE_CXX_COMPILER=clang++ -DSIMDJSON_DEVELOPER_MODE=ON -DSIMDJSON_STATIC_REFLECTION=ON -DBUILD_SHARED_LIBS=OFF ..
-cmake --build . --target benchmark_serialization_twitter
-
-# No SIMD Escaping variant
-cmake -DCMAKE_CXX_COMPILER=clang++ -DSIMDJSON_DEVELOPER_MODE=ON -DSIMDJSON_STATIC_REFLECTION=ON -DBUILD_SHARED_LIBS=OFF -DCMAKE_CXX_FLAGS="-DSIMDJSON_ABLATION_NO_SIMD_ESCAPING" ..
-
-# No Consteval variant
-cmake -DCMAKE_CXX_COMPILER=clang++ -DSIMDJSON_DEVELOPER_MODE=ON -DSIMDJSON_STATIC_REFLECTION=ON -DBUILD_SHARED_LIBS=OFF -DCMAKE_CXX_FLAGS="-DSIMDJSON_ABLATION_NO_CONSTEVAL" ..
-
-# No Branch Hints variant
-cmake -DCMAKE_CXX_COMPILER=clang++ -DSIMDJSON_DEVELOPER_MODE=ON -DSIMDJSON_STATIC_REFLECTION=ON -DBUILD_SHARED_LIBS=OFF -DCMAKE_CXX_FLAGS="-DSIMDJSON_ABLATION_NO_BRANCH_HINTS" ..
-
-# Linear Buffer Growth variant
-cmake -DCMAKE_CXX_COMPILER=clang++ -DSIMDJSON_DEVELOPER_MODE=ON -DSIMDJSON_STATIC_REFLECTION=ON -DBUILD_SHARED_LIBS=OFF -DCMAKE_CXX_FLAGS="-DSIMDJSON_ABLATION_LINEAR_GROWTH" ..
-
-# No String Escape Fast Path variant
-cmake -DCMAKE_CXX_COMPILER=clang++ -DSIMDJSON_DEVELOPER_MODE=ON -DSIMDJSON_STATIC_REFLECTION=ON -DBUILD_SHARED_LIBS=OFF -DCMAKE_CXX_FLAGS="-DSIMDJSON_ABLATION_NO_ESCAPE_FAST_PATH" ..
-```
-
----
-
-**Study completed successfully with actionable insights for the simdjson reflection presentation.**

ablation/ABLATION_RESULTS.md

@@ -1,209 +0,0 @@
-# Ablation Study Results
-
-This document presents the performance impact analysis of various optimizations in simdjson's C++26 reflection-based JSON serialization.
-
-## Methodology
-
-The ablation study systematically disables individual optimizations to measure their contribution to overall performance. Each variant is tested with:
-- Twitter dataset (631KB) - 10 iterations
-- CITM dataset (synthetic) - 20 iterations
-
-## Optimization Variants
-
-1. **baseline** - All optimizations enabled
-2. **no_consteval** - Disables compile-time string processing
-3. **no_simd_escaping** - Disables SIMD-accelerated string escaping
-4. **no_fast_digits** - Disables optimized integer-to-string conversion
-5. **no_branch_hints** - Disables CPU branch prediction hints
-6. **linear_growth** - Uses linear instead of exponential buffer growth
-
-## Current Results (September 2025)
-
-### Parsing Performance (JSON → C++ Structs)
-
-#### Twitter Parsing (631KB)
-| Optimization | Throughput | Impact When Disabled | Notes |
-|--------------|------------|---------------------|-------|
-| **Baseline** | 3708 MB/s | - | All optimizations |
-| No Consteval | 3700 MB/s | -0.2% | **No impact on parsing** |
-| No SIMD Escaping | ~3700 MB/s | ~0% | Minimal impact |
-| No Fast Digits | ~3600 MB/s | ~-3% | Small impact |
-| No Branch Hints | ~3650 MB/s | ~-1.5% | Minimal impact |
-| Linear Growth | ~3680 MB/s | ~-0.8% | Minimal impact |
-
-#### CITM Parsing (1.7MB)
-| Optimization | Throughput | Impact When Disabled | Notes |
-|--------------|------------|---------------------|-------|
-| **Baseline** | 2246 MB/s | - | All optimizations |
-| No Consteval | 2214 MB/s | -1.4% | **No impact on parsing** |
-| No SIMD Escaping | ~2240 MB/s | ~0% | Minimal impact |
-| No Fast Digits | ~2180 MB/s | ~-3% | Small impact |
-| No Branch Hints | ~2220 MB/s | ~-1% | Minimal impact |
-| Linear Growth | ~2230 MB/s | ~-0.7% | Minimal impact |
-
-### Serialization Performance (C++ Structs → JSON)
-
-#### Twitter Serialization (631KB, String-Heavy) - Apple Silicon
-| Optimization | Throughput | Impact When Disabled | Contribution |
-|--------------|------------|---------------------|--------------|
-| **Baseline** | 3211 MB/s | - | All optimizations |
-| No Consteval | 1607 MB/s | -50.0% | **+100% performance** |
-| No SIMD Escaping | 2269 MB/s | -29.3% | **+42% performance** |
-| No Fast Digits | 3035 MB/s | -5.5% | +6% performance |
-| No Branch Hints | 3182 MB/s | -0.9% | +1% performance |
-| Linear Growth | 3225 MB/s | +0.4% | -0.4% performance |
-
-#### CITM Serialization (1.7MB, Complex Objects) - Apple Silicon
-| Optimization | Throughput | Impact When Disabled | Contribution |
-|--------------|------------|---------------------|--------------|
-| **Baseline** | 2360 MB/s | - | All optimizations |
-| No Consteval | 978 MB/s | -58.6% | **+141% performance** |
-| No SIMD Escaping | 2259 MB/s | -4.3% | +4% performance |
-| No Fast Digits | 1767 MB/s | -25.1% | **+34% performance** |
-| No Branch Hints | 2247 MB/s | -4.8% | +5% performance |
-| Linear Growth | 2290 MB/s | -3.0% | +3% performance |
-
-## Key Findings
-
-### Parsing vs Serialization Impact
-1. **Consteval affects ONLY serialization**:
-   - Parsing: No impact (runtime data, can't be optimized at compile-time)
-   - Serialization: 100-130% improvement (field names known at compile-time)
-
-2. **SIMD escaping primarily affects serialization**:
-   - Parsing: Minimal impact (already uses SIMD for parsing)
-   - Serialization: 40% improvement (escaping output strings)
-
-3. **Most optimizations target serialization**:
-   - Parsing is already near-optimal with simdjson's core SIMD algorithms
-   - Serialization benefits from compile-time and runtime optimizations
-
-### Overall Performance (Apple Silicon)
-- **Parsing**: 4.1 GB/s (Twitter), 2.7 GB/s (CITM) - consistent across variants
-- **Serialization**: 3.2 GB/s (Twitter), 2.4 GB/s (CITM) - heavily optimization-dependent
-- **Combined optimizations**: Provide 2-2.4x performance for serialization
-
-## Code Snippets for Each Optimization
-
-### 1. Consteval (Compile-Time String Processing)
-
-When enabled, field names are processed at compile-time:
-
-```cpp
-#if SIMDJSON_CONSTEVAL && !defined(SIMDJSON_ABLATION_NO_CONSTEVAL)
-// Specialization for consteval optimization
-template<typename T>
-struct atom_struct_impl<T, true> {
-  template<class builder_type>
-  static void serialize(builder_type& b, const T& t) {
-    b.append_object_start();
-    [:expand(nonstatic_data_members_of(^^T)):] >> [&]<auto mem> {
-      constexpr std::string_view key = identifier_of(mem);
-      // Field name is compile-time constant, can be optimized
-      constexpr auto quoted_key = consteval_to_quoted_escaped(key);
-      b.append_string(quoted_key);
-      b.append_colon();
-      b.append(t.[:mem:]);
-      b.append_comma();
-    };
-    b.append_object_end();
-  }
-};
-#else
-// Runtime fallback - field names processed at runtime
-b.append_key(key);  // Must escape and quote at runtime
-#endif
-```
-
-### 2. SIMD String Escaping
-
-Fast SIMD-based string escaping for JSON output:
-
-```cpp
-#ifdef SIMDJSON_ABLATION_NO_SIMD_ESCAPING
-simdjson_inline bool fast_needs_escaping(std::string_view view) {
-  return simple_needs_escaping(view);  // Character-by-character check
-}
-#else
-simdjson_inline bool fast_needs_escaping(std::string_view view) {
-  // SIMD implementation - check 16 bytes at once
-  const uint8_t* data = reinterpret_cast<const uint8_t*>(view.data());
-  size_t len = view.length();
-  size_t i = 0;
-
-  for (; i + 16 <= len; i += 16) {
-    __m128i chunk = _mm_loadu_si128((__m128i*)(data + i));
-    // Check for characters that need escaping: ", \, control chars
-    __m128i needs_escape = /* SIMD logic */;
-    if (!_mm_testz_si128(needs_escape, needs_escape)) {
-      return true;
-    }
-  }
-  // Handle remaining bytes...
-}
-#endif
-```
-
-### 3. Fast Integer-to-String Conversion
-
-Optimized digit counting and conversion:
-
-```cpp
-#ifdef SIMDJSON_ABLATION_NO_FAST_DIGITS
-  // Fallback: use standard library conversion
-  return std::to_string(v).length();
-#else
-  // Fast digit counting using bit operations
-  if (sizeof(number_type) == 8) {
-    // Use DeBruijn-like technique for 64-bit
-    int leading_zeros = __builtin_clzll(v | 1);
-    int bits = 64 - leading_zeros;
-    // Table lookup based on bits to get digit count
-    return digit_count_table[bits];
-  }
-  // Similar optimizations for 32-bit, 16-bit...
-#endif
-```
-
-### 4. Branch Prediction Hints
-
-CPU branch prediction optimization:
-
-```cpp
-#ifdef SIMDJSON_ABLATION_NO_BRANCH_HINTS
-  if (upcoming_bytes <= capacity - position) {
-    return true;
-  }
-#else
-  if (simdjson_likely(upcoming_bytes <= capacity - position)) {
-    return true;  // Fast path - buffer has space (most common)
-  }
-#endif
-  // Slow path - need to grow buffer
-```
-
-### 5. Buffer Growth Strategy
-
-Exponential vs linear buffer growth:
-
-```cpp
-#ifdef SIMDJSON_ABLATION_LINEAR_GROWTH
-  grow_buffer(position + upcoming_bytes + 1024); // Linear: add 1KB
-#else
-  // Exponential growth for better amortized performance
-  size_t new_capacity = capacity;
-  while (new_capacity < position + upcoming_bytes) {
-    new_capacity *= 2;  // Double the buffer size
-  }
-  grow_buffer(new_capacity);
-#endif
-```
-
-## Running the Study
-
-```bash
-cd /path/to/simdjson
-./ablation/run_serialization_ablation.sh
-```
-
-Results are saved to `ablation/results/` (gitignored).

ablation/serialization_test.cpp

@@ -1,217 +0,0 @@
-// Unified serialization test for ablation study
-// Tests both Twitter and CITM datasets using optimized string_builder
-
-#include <iostream>
-#include <chrono>
-#include <vector>
-#include <string>
-#include <cstring>
-#include <simdjson.h>
-
-using namespace simdjson;
-
-// Benchmark Twitter serialization with proper builder reuse
-double benchmark_twitter(int iterations = 1000) {
-    // Create synthetic Twitter-like data
-    std::vector<std::string> tweets;
-    for (int i = 0; i < 100; i++) {
-        tweets.push_back("This is tweet " + std::to_string(i) + " with @mentions and #hashtags https://example.com/link and more content to make it realistic");
-    }
-
-    // Create reusable string_builder outside the loop
-    simdjson::arm64::builder::string_builder sb;
-
-    // Warmup
-    for (int i = 0; i < 100; i++) {
-        sb.clear();
-        sb.append("{\"statuses\":[");
-
-        for (size_t j = 0; j < tweets.size(); j++) {
-            if (j > 0) sb.append(',');
-
-            sb.append("{\"created_at\":\"Mon Sep 24 03:35:21 +0000 2012\",");
-            sb.append("\"id\":");
-            sb.append(uint64_t(505874924095815700ULL + j));
-            sb.append(",\"text\":\"");
-            sb.append(tweets[j]);
-            sb.append("\",\"user\":{");
-            sb.append("\"id\":");
-            sb.append(uint64_t(1186275104 + j));
-            sb.append(",\"screen_name\":\"user_");
-            sb.append(uint64_t(j));
-            sb.append("\",\"name\":\"User ");
-            sb.append(uint64_t(j));
-            sb.append("\",\"verified\":");
-            sb.append(j % 2 == 0);
-            sb.append(",\"followers_count\":");
-            sb.append(uint64_t(1000 + j * 10));
-            sb.append("},\"retweet_count\":");
-            sb.append(uint64_t(j * 2));
-            sb.append(",\"favorite_count\":");
-            sb.append(uint64_t(j * 5));
-            sb.append("}");
-        }
-
-        sb.append("]}");
-        std::string_view result;
-        sb.view().get(result);
-    }
-
-    // Benchmark
-    auto start = std::chrono::steady_clock::now();
-
-    size_t total_size = 0;
-    for (int i = 0; i < iterations; i++) {
-        sb.clear();  // Clear and reuse the builder
-        sb.append("{\"statuses\":[");
-
-        for (size_t j = 0; j < tweets.size(); j++) {
-            if (j > 0) sb.append(',');
-
-            sb.append("{\"created_at\":\"Mon Sep 24 03:35:21 +0000 2012\",");
-            sb.append("\"id\":");
-            sb.append(uint64_t(505874924095815700ULL + j));
-            sb.append(",\"text\":\"");
-            sb.append(tweets[j]);
-            sb.append("\",\"user\":{");
-            sb.append("\"id\":");
-            sb.append(uint64_t(1186275104 + j));
-            sb.append(",\"screen_name\":\"user_");
-            sb.append(uint64_t(j));
-            sb.append("\",\"name\":\"User ");
-            sb.append(uint64_t(j));
-            sb.append("\",\"verified\":");
-            sb.append(j % 2 == 0);
-            sb.append(",\"followers_count\":");
-            sb.append(uint64_t(1000 + j * 10));
-            sb.append("},\"retweet_count\":");
-            sb.append(uint64_t(j * 2));
-            sb.append(",\"favorite_count\":");
-            sb.append(uint64_t(j * 5));
-            sb.append("}");
-        }
-
-        sb.append("]}");
-        std::string_view result;
-        sb.view().get(result);
-        total_size = result.size();
-    }
-
-    auto end = std::chrono::steady_clock::now();
-    auto duration = std::chrono::duration_cast<std::chrono::microseconds>(end - start);
-
-    double seconds = duration.count() / 1000000.0;
-    double mb_per_sec = (total_size * iterations / 1024.0 / 1024.0) / seconds;
-
-    return mb_per_sec;
-}
-
-// Benchmark CITM serialization with proper builder reuse
-double benchmark_citm(int iterations = 500) {
-    // Create CITM-like data with nested structures
-    std::vector<std::string> names;
-    std::vector<std::string> descriptions;
-
-    for (int i = 0; i < 200; i++) {
-        names.push_back("Event " + std::to_string(i) + " - Concert Series");
-        descriptions.push_back("Description for event " + std::to_string(i) + " with details");
-    }
-
-    // Create reusable string_builder outside the loop
-    simdjson::arm64::builder::string_builder sb;
-
-    // Warmup
-    for (int i = 0; i < 50; i++) {
-        sb.clear();
-        sb.append("{\"events\":[],\"performances\":[]}");
-        std::string_view result;
-        sb.view().get(result);
-    }
-
-    // Benchmark
-    auto start = std::chrono::steady_clock::now();
-
-    size_t total_size = 0;
-    for (int iter = 0; iter < iterations; iter++) {
-        sb.clear();  // Clear and reuse the builder
-        sb.append("{\"events\":[");
-
-        for (size_t i = 0; i < names.size(); i++) {
-            if (i > 0) sb.append(',');
-            sb.append("{\"id\":");
-            sb.append(uint64_t(138586341 + i));
-            sb.append(",\"name\":\"");
-            sb.append(names[i]);
-            sb.append("\",\"description\":\"");
-            sb.append(descriptions[i]);
-            sb.append("\",\"topicIds\":[");
-            sb.append(uint64_t(324846099 + i));
-            sb.append(",");
-            sb.append(uint64_t(107888604 + i));
-            sb.append("]}");
-        }
-
-        sb.append("],\"performances\":[");
-
-        for (int i = 0; i < 500; i++) {
-            if (i > 0) sb.append(',');
-            sb.append("{\"id\":");
-            sb.append(uint64_t(339420000 + i));
-            sb.append(",\"eventId\":");
-            sb.append(uint64_t(138586341 + (i % 200)));
-            sb.append(",\"start\":");
-            sb.append(uint64_t(1572892800 + i * 3600));
-            sb.append(",\"venueCode\":\"VENUE_");
-            sb.append(uint64_t(i % 10));
-            sb.append("\"}");
-        }
-
-        sb.append("],\"venues\":[");
-
-        for (int i = 0; i < 50; i++) {
-            if (i > 0) sb.append(',');
-            sb.append("{\"id\":");
-            sb.append(uint64_t(1000 + i));
-            sb.append(",\"name\":\"Venue ");
-            sb.append(uint64_t(i));
-            sb.append("\",\"capacity\":");
-            sb.append(uint64_t(5000 + i * 100));
-            sb.append("}");
-        }
-
-        sb.append("]}");
-        std::string_view result;
-        sb.view().get(result);
-        total_size = result.size();
-    }
-
-    auto end = std::chrono::steady_clock::now();
-    auto duration = std::chrono::duration_cast<std::chrono::microseconds>(end - start);
-
-    double seconds = duration.count() / 1000000.0;
-    double mb_per_sec = (total_size * iterations / 1024.0 / 1024.0) / seconds;
-
-    return mb_per_sec;
-}
-
-int main(int argc, char* argv[]) {
-    if (argc != 2) {
-        std::cerr << "Usage: " << argv[0] << " <twitter|citm>" << std::endl;
-        return 1;
-    }
-
-    std::string test_type = argv[1];
-
-    if (test_type == "twitter") {
-        double mb_per_sec = benchmark_twitter();
-        std::cout << mb_per_sec << std::endl;
-    } else if (test_type == "citm") {
-        double mb_per_sec = benchmark_citm();
-        std::cout << mb_per_sec << std::endl;
-    } else {
-        std::cerr << "Unknown test type: " << test_type << std::endl;
-        return 1;
-    }
-
-    return 0;
-}

ablation_guide.md

@@ -1,297 +0,0 @@
-# Ablation Study Guide - simdjson C++26 Reflection
-
-This guide explains how to run and analyze ablation studies for the simdjson C++26 reflection-based JSON serialization implementation.
-
-## Prerequisites
-
-1. **Compiler**: Clang with C++26 reflection support (bloomberg/clang-p2996)
-2. **Build Tools**: CMake 3.25+, Make
-3. **Analysis Tools**: Python 3, bc (basic calculator)
-4. **System**: Linux/macOS with sufficient memory for compilation
-
-## Quick Start
-
-### Running the Complete Ablation Study
-
-```bash
-# Run both benchmarks with defaults (10 runs Twitter, 20 runs CITM)
-./ablation_study.sh
-
-# Run only Twitter benchmark with custom runs
-./ablation_study.sh -b twitter -r 20
-
-# Run with compilation time measurement
-./ablation_study.sh --compilation-time
-
-# Analyze results
-python3 calculate_stats.py
-```
-
-## Important: Baseline Performance Verification
-
-**CRITICAL**: Before running any ablation study, verify that your baseline performance is approximately **3,200 MB/s** for the Twitter benchmark. If you see significantly lower numbers (e.g., ~1,600 MB/s), the consteval optimization may not be active.
-
-### Verify Baseline Performance
-
-```bash
-cd build
-cmake .. -DCMAKE_CXX_COMPILER=clang++ \
-         -DSIMDJSON_DEVELOPER_MODE=ON \
-         -DSIMDJSON_STATIC_REFLECTION=ON \
-         -DBUILD_SHARED_LIBS=OFF \
-         -DCMAKE_BUILD_TYPE=Release
-make benchmark_serialization_twitter -j4
-./benchmark/static_reflect/twitter_benchmark/benchmark_serialization_twitter -f simdjson_static_reflection
-```
-
-Expected output:
-```
-bench_simdjson_static_reflection : 3164.70 MB/s   0.79 Ms/s
-```
-
-If you see ~1,600 MB/s instead, try:
-1. Clean rebuild: `rm -rf build/*`
-2. Verify include files are correct in `json_builder.h`
-3. Check that `SIMDJSON_CONSTEVAL` is defined
-
-## Understanding the Ablation Study
-
-### What It Measures
-
-The ablation study systematically disables optimizations to measure their individual contributions:
-
-1. **Baseline**: All optimizations enabled (reference)
-2. **No Consteval**: Disables compile-time string processing
-3. **No SIMD Escaping**: Disables vectorized string escaping
-4. **No Fast Digits**: Disables optimized integer-to-string conversion
-5. **No Branch Hints**: Disables CPU branch prediction hints
-6. **Linear Growth**: Uses linear instead of exponential buffer growth
-
-### Output Format
-
-Results are saved in CSV format to the `ablation_results` directory:
-- `twitter_ablation_results.csv`: Twitter benchmark results
-- `citm_ablation_results.csv`: CITM benchmark results
-- `ablation_summary.txt`: Human-readable summary
-
-CSV format:
-```
-Variant,Mean_MB/s,StdDev,CV%,Runs,Impact%,CompileTime_s
-baseline,3164.70,36.93,1.17,10,0,44.02
-no_consteval,1571.96,26.00,1.65,10,-50.3,40.31
-```
-
-## Step-by-Step Process
-
-### 1. Prepare the Environment
-
-```bash
-# Navigate to simdjson directory
-cd /path/to/simdjson
-
-# Ensure build directory exists
-mkdir -p build
-
-# Make scripts executable
-chmod +x ablation_study.sh
-chmod +x calculate_stats.py
-```
-
-### 2. Run the Ablation Study
-
-```bash
-# Basic run (both benchmarks with optimal runs)
-./ablation_study.sh
-
-# Advanced options
-./ablation_study.sh --help
-
-# Run only CITM with custom runs (due to high variance)
-./ablation_study.sh -b citm -c 30
-
-# Include compilation time measurements
-./ablation_study.sh --compilation-time
-
-# Verbose mode for debugging
-./ablation_study.sh --verbose
-```
-
-#### Key Options
-
-- `-b, --benchmark`: Choose twitter, citm, or both (default: both)
-- `-r, --runs`: Number of runs for Twitter (default: 10)
-- `-c, --citm-runs`: Number of runs for CITM (default: 20 due to higher variance)
-- `--compilation-time`: Also measure compilation time for each variant
-- `-o, --output`: Output directory for results (default: ablation_results)
-
-### 3. Monitor Progress
-
-The script will show progress for each variant:
-```
-=== Processing variant: baseline ===
-Results: Twitter,baseline,3164.70,36.93,10,44.02s compilation
-
-=== Processing variant: no_consteval ===
-Results: Twitter,no_consteval,1571.96,26.00,10,40.31s compilation
-```
-
-### 4. Analyze Results
-
-```bash
-# Process results with statistics
-python3 calculate_stats.py
-
-# Or specify a custom results file
-python3 calculate_stats.py my_ablation_results.txt
-```
-
-Output will show:
-- Mean throughput for each variant
-- Standard deviation and coefficient of variation
-- Performance impact relative to baseline
-- Compilation time differences
-
-Example output:
-```
-================================================================================
-Twitter Benchmark Results
-================================================================================
-
-Variant                   Mean (MB/s)  StdDev     CV (%)   Impact       Compile (s)
-------------------------- ------------ ---------- -------- ------------ ------------
-**Baseline**              3164.70      ±36.93     1.17     Reference    44.02
-No Consteval              1571.96      ±26.00     1.65     -50.3%       40.31
-No Simd Escaping          2285.77      ±33.34     1.46     -27.8%       41.51
-```
-
-## Troubleshooting
-
-### Issue: Low Baseline Performance
-
-If baseline is ~1,600 MB/s instead of ~3,200 MB/s:
-
-1. **Clean rebuild**:
-   ```bash
-   cd build
-   rm -rf *
-   cmake .. # with proper flags
-   make benchmark_serialization_twitter -j4
-   ```
-
-2. **Check consteval is working**:
-   ```bash
-   # Look for SIMDJSON_CONSTEVAL in the output
-   cmake .. -DCMAKE_BUILD_TYPE=Release -DSIMDJSON_STATIC_REFLECTION=ON -DCMAKE_VERBOSE_MAKEFILE=ON
-   ```
-
-3. **Verify includes**: Check that `json_builder.h` includes `json_string_builder-inl.h`
-
-### Issue: CITM Benchmark Fails
-
-The CITM benchmark has been fixed using `std::define_static_string`. If you still encounter issues, check `citm_issue.md` for details.
-
-### Issue: Script Permissions
-
-```bash
-chmod +x ablation_study.sh
-chmod +x calculate_stats.py
-```
-
-### Issue: Missing Dependencies
-
-```bash
-# Install bc (basic calculator)
-sudo apt-get install bc  # Ubuntu/Debian
-brew install bc          # macOS
-```
-
-## Manual Testing
-
-To test individual optimization variants manually:
-
-```bash
-cd build
-
-# Test specific variant
-cmake .. -DCMAKE_CXX_FLAGS="-DSIMDJSON_ABLATION_NO_CONSTEVAL" -DCMAKE_BUILD_TYPE=Release
-make benchmark_serialization_twitter -j4
-./benchmark/static_reflect/twitter_benchmark/benchmark_serialization_twitter -f simdjson_static_reflection
-```
-
-## Understanding Results
-
-### Performance Tiers
-
-1. **Critical Optimizations (>25% impact)**:
-   - Consteval: ~50% performance improvement
-   - SIMD Escaping: ~28% performance improvement
-
-2. **Moderate Optimizations (5-10% impact)**:
-   - Fast Digits: ~7% performance improvement
-
-3. **Minor Optimizations (<5% impact)**:
-   - Branch Hints: ~2% performance improvement
-   - Buffer Growth Strategy: ~2% performance improvement
-
-### Compilation Time
-
-Interestingly, optimizations generally *reduce* compilation time:
-- Baseline: ~44 seconds
-- With optimizations disabled: ~40-42 seconds
-
-This suggests that compile-time computation (consteval) actually speeds up overall compilation.
-
-## Advanced Usage
-
-### Running Specific Variants Only
-
-Modify the `ABLATION_VARIANTS` array in `ablation_study.sh`:
-
-```bash
-declare -A ABLATION_VARIANTS=(
-    ["baseline"]=""
-    ["no_consteval"]="-DSIMDJSON_ABLATION_NO_CONSTEVAL"
-    # Add or remove variants as needed
-)
-```
-
-### Custom Benchmarks
-
-To add a new benchmark:
-
-1. Add benchmark path to the script
-2. Update the benchmark selection logic
-3. Ensure the benchmark follows the expected output format
-
-### Integration with CI/CD
-
-```yaml
-# Example GitHub Actions workflow
-- name: Run Ablation Study
-  run: |
-    ./ablation_study.sh -r 5 -c 10 -o ci_results
-    python3 calculate_stats.py ci_results > ablation_summary.txt
-
-- name: Upload Results
-  uses: actions/upload-artifact@v3
-  with:
-    name: ablation-results
-    path: |
-      ci_ablation_results.txt
-      ablation_summary.txt
-```
-
-## Best Practices
-
-1. **Consistency**: Always run the same number of iterations for reliable comparisons
-2. **Clean State**: Start with a clean build directory for each full study
-3. **System Load**: Run on a quiet system to minimize variance
-4. **Temperature**: Allow system to cool between runs if thermal throttling is a concern
-5. **Documentation**: Record system specs and compiler versions with results
-
-## Further Reading
-
-- `ablation_results.md`: Detailed analysis of optimization impacts
-- `citm_issue.md`: Technical details about CITM compilation issues and resolution
-- `ablation_study.sh`: Unified script source code with inline documentation
-- `calculate_stats.py`: Statistical analysis implementation

ablation_results.md

@@ -1,406 +0,0 @@
-# Ablation Study Results - simdjson C++26 Reflection Serialization
-
-## Methodology
-
-This ablation study evaluates the performance impact of various optimizations in simdjson's C++26 reflection-based JSON serialization implementation. The study uses a systematic approach to disable individual optimizations and measure their contribution to overall performance.
-
-### Test Environment
-
-- **Compiler**: Clang 21.0.0 (bloomberg/clang-p2996) with C++26 reflection support
-- **Platform**: aarch64-unknown-linux-gnu
-- **Build Type**: Release with `-O3` optimization
-- **Benchmarks**:
-  - Twitter JSON (93,311 bytes) - Complete Twitter API response
-  - CITM Catalog (41,631 bytes) - Event catalog with maps and nested objects
-- **Methodology**: 10 runs for Twitter, 20 runs for CITM per variant with statistical analysis
-- **Date**: July 31, 2025
-
-### Measurement Approach
-
-Each optimization variant is tested by:
-1. Rebuilding the library with specific ablation flags
-2. Running the benchmark 10 times to ensure statistical significance
-3. Calculating mean, standard deviation, and confidence intervals
-4. Measuring both runtime performance and compilation time impact
-
-## Instructions to Reproduce
-
-### Quick Start
-
-```bash
-# Run the complete ablation study for both benchmarks with compilation time measurement
-./ablation_study.sh --compilation-time
-
-# Analyze the results
-python3 calculate_stats.py
-
-# View the summary
-cat ablation_results/ablation_summary.txt
-```
-
-### Detailed Instructions
-
-1. **Prepare the environment**:
-   ```bash
-   # Ensure you're in the simdjson root directory
-   cd /path/to/simdjson
-
-   # Make scripts executable
-   chmod +x ablation_study.sh
-   chmod +x calculate_stats.py
-
-   # Verify build directory exists
-   mkdir -p build
-   ```
-
-2. **Run the ablation study**:
-   ```bash
-   # Full study with optimal settings (10 runs Twitter, 20 runs CITM, with compilation time)
-   ./ablation_study.sh --compilation-time
-
-   # Alternative: Run only one benchmark
-   ./ablation_study.sh -b twitter -r 15              # Twitter only with 15 runs
-   ./ablation_study.sh -b citm -c 30                # CITM only with 30 runs
-
-   # Alternative: Skip compilation time measurement for faster results
-   ./ablation_study.sh                              # Both benchmarks, no compilation time
-   ```
-
-3. **Analyze the results**:
-   ```bash
-   # Generate statistical analysis
-   python3 calculate_stats.py
-
-   # Alternative: Analyze results from a custom directory
-   python3 calculate_stats.py /path/to/custom/results
-   ```
-
-4. **View the outputs**:
-   ```bash
-   # Results are saved in the ablation_results directory:
-   ls ablation_results/
-   # twitter_ablation_results.csv    - Raw Twitter benchmark data
-   # citm_ablation_results.csv       - Raw CITM benchmark data
-   # ablation_summary.txt            - Human-readable summary
-
-   # View the summary
-   cat ablation_results/ablation_summary.txt
-   ```
-
-### Prerequisites
-
-1. **Compiler**: Clang with C++26 reflection support (bloomberg/clang-p2996)
-2. **Build Tools**: CMake 3.25+, Make
-3. **Runtime Tools**: Python 3, bc (calculator)
-4. **Performance Check**: Ensure baseline Twitter performance is ~3,200 MB/s before starting
-
-### Expected Runtime
-
-- Twitter benchmark (10 runs × 6 variants): ~2 minutes
-- CITM benchmark (20 runs × 6 variants): ~4 minutes
-- Compilation time measurement adds: ~5 minutes
-- **Total with compilation time**: ~11 minutes
-
-### Manual Testing of Individual Variants
-
-```bash
-# Example: Test No SIMD Escaping variant manually
-cd build
-cmake .. -DCMAKE_CXX_FLAGS="-DSIMDJSON_ABLATION_NO_SIMD_ESCAPING" -DCMAKE_BUILD_TYPE=Release
-make benchmark_serialization_twitter -j4
-./benchmark/static_reflect/twitter_benchmark/benchmark_serialization_twitter -f simdjson_static_reflection
-```
-
-## Optimization Details
-
-### 1. Consteval Optimization (`SIMDJSON_ABLATION_NO_CONSTEVAL`)
-
-**Purpose**: Enables compile-time string processing for JSON field names using C++26 reflection and `std::define_static_string` from P3491R3.
-
-**Location**: `include/simdjson/generic/ondemand/json_builder.h:83-106`
-
-**Implementation**:
-```cpp
-#if SIMDJSON_CONSTEVAL && !defined(SIMDJSON_ABLATION_NO_CONSTEVAL)
-template<typename T>
-struct atom_struct_impl<T, true> {
-  static void serialize(string_builder &b, const T &t) {
-    b.append('{');
-    bool first = true;
-    [:expand(std::meta::nonstatic_data_members_of(^^T, std::meta::access_context::unchecked())):] >> [&]<auto dm>() {
-      if (!first)
-        b.append(',');
-      first = false;
-      // Create a compile-time string using define_static_string
-      constexpr auto escaped_name = consteval_to_quoted_escaped(std::meta::identifier_of(dm));
-      constexpr const char* static_key = std::define_static_string(escaped_name);
-      b.append_raw(static_key);
-      b.append(':');
-      atom(b, t.[:dm:]);
-    };
-    b.append('}');
-  }
-};
-#else
-  // Runtime fallback: string concatenation at runtime
-  std::string key = "\"" + std::string(std::meta::identifier_of(dm)) + "\"";
-#endif
-```
-
-**What it does**: Pre-computes escaped JSON field names at compile time and promotes them to static storage using `std::define_static_string`, avoiding runtime string allocation and escaping overhead.
-
-### 2. SIMD String Escaping (`SIMDJSON_ABLATION_NO_SIMD_ESCAPING`)
-
-**Purpose**: Uses vectorized instructions to check if strings need escaping.
-
-**Location**: `include/simdjson/generic/ondemand/json_string_builder-inl.h:86-120`
-
-**Implementation**:
-```cpp
-#ifdef SIMDJSON_ABLATION_NO_SIMD_ESCAPING
-simdjson_inline bool fast_needs_escaping(std::string_view view) {
-  return simple_needs_escaping(view);  // Scalar fallback
-}
-#elif SIMDJSON_EXPERIMENTAL_HAS_SSE2
-simdjson_inline bool fast_needs_escaping(std::string_view view) {
-  const char* p = view.data();
-  const char* end = p + view.size();
-
-  // Process 16 bytes at a time with SIMD
-  const __m128i quote_mask = _mm_set1_epi8('"');
-  const __m128i backslash_mask = _mm_set1_epi8('\\');
-  const __m128i below_32_mask = _mm_set1_epi8(32);
-
-  while (end - p >= 16) {
-    __m128i v = _mm_loadu_si128(reinterpret_cast<const __m128i*>(p));
-    __m128i quotes = _mm_cmpeq_epi8(v, quote_mask);
-    __m128i backslashes = _mm_cmpeq_epi8(v, backslash_mask);
-    __m128i below_32 = _mm_cmplt_epi8(v, below_32_mask);
-    __m128i needs_escape = _mm_or_si128(_mm_or_si128(quotes, backslashes), below_32);
-
-    if (_mm_movemask_epi8(needs_escape)) {
-      return true;
-    }
-    p += 16;
-  }
-  // Handle remaining bytes with scalar code
-  return simple_needs_escaping(std::string_view(p, end - p));
-}
-#endif
-```
-
-**What it does**: Processes 16 bytes at a time to check for characters that need JSON escaping (quotes, backslashes, control characters).
-
-### 3. Fast Digit Counting (`SIMDJSON_ABLATION_NO_FAST_DIGITS`)
-
-**Purpose**: Optimizes integer-to-string conversion by pre-computing digit counts.
-
-**Location**: `include/simdjson/generic/ondemand/json_string_builder-inl.h:449-490`
-
-**Implementation**:
-```cpp
-template <typename number_type>
-simdjson_inline size_t digit_count(number_type v) noexcept {
-#ifdef SIMDJSON_ABLATION_NO_FAST_DIGITS
-  // Fallback: use standard library conversion to count digits
-  return std::to_string(v).length();
-#else
-  return fast_digit_count(v);  // Optimized bit manipulation
-#endif
-}
-
-// Fast implementation using logarithmic properties
-simdjson_inline int fast_digit_count(uint32_t x) noexcept {
-  // Avoid 64-bit math as much as possible.
-  // Adapted from: https://johnnylee-sde.github.io/Fast-digit-counting/
-  static constexpr uint32_t table[] = {
-    9, 99, 999, 9999, 99999, 999999, 9999999,
-    99999999, 999999999
-  };
-  int log2 = 31 - __builtin_clz(x | 1);
-  uint32_t digits = (log2 + 1) * 1233 >> 12;
-  return digits + (x > table[digits - 1]);
-}
-```
-
-**What it does**: Avoids expensive string allocation and formatting by using bit manipulation and lookup tables to count digits.
-
-### 4. Branch Prediction Hints (`SIMDJSON_ABLATION_NO_BRANCH_HINTS`)
-
-**Purpose**: Provides hints to the CPU's branch predictor for better instruction pipelining.
-
-**Location**: `include/simdjson/generic/ondemand/json_string_builder-inl.h:309-317`
-
-**Implementation**:
-```cpp
-#ifdef SIMDJSON_ABLATION_NO_BRANCH_HINTS
-  if (upcoming_bytes <= capacity - position) {
-    return true;
-  }
-  if (position + upcoming_bytes < position) {  // Overflow check
-    return false;
-  }
-#else
-  if (simdjson_likely(upcoming_bytes <= capacity - position)) {
-    return true;  // Fast path: enough space
-  }
-  if (simdjson_unlikely(position + upcoming_bytes < position)) {
-    return false;  // Overflow detected
-  }
-#endif
-
-// Where simdjson_likely/unlikely are defined as:
-#define simdjson_likely(x) __builtin_expect(!!(x), 1)
-#define simdjson_unlikely(x) __builtin_expect(!!(x), 0)
-```
-
-**What it does**: Helps CPU predict which branches are more likely, reducing pipeline stalls.
-
-### 5. Buffer Growth Strategy (`SIMDJSON_ABLATION_LINEAR_GROWTH`)
-
-**Purpose**: Controls memory allocation strategy for the output buffer.
-
-**Location**: `include/simdjson/generic/ondemand/json_string_builder-inl.h:327-332`
-
-**Implementation**:
-```cpp
-#ifdef SIMDJSON_ABLATION_LINEAR_GROWTH
-  // Linear growth: add fixed 1KB chunks
-  grow_buffer(position + upcoming_bytes + 1024);
-#else
-  // Exponential growth: double the capacity
-  grow_buffer((std::max)(capacity * 2, position + upcoming_bytes));
-#endif
-```
-
-**What it does**: Exponential growth reduces the number of reallocations for large outputs, trading memory for speed.
-
-## Performance Results
-
-### Twitter Benchmark Results (10 Runs)
-
-| Optimization Variant | Mean (MB/s) | Std Dev | CV (%) | Runtime Impact | Compilation Time (s) | Compilation Impact |
-|---------------------|-------------|---------|--------|----------------|---------------------|-------------------|
-| **Baseline** | **3,235.16** | ±20.78 | 0.64 | **Reference** | 22.88 | **Reference** |
-| No Consteval | 1,610.22 | ±19.22 | 1.19 | **-50.2%** | 23.06 | +0.8% |
-| No SIMD Escaping | 2,280.01 | ±22.07 | 0.97 | **-29.5%** | 22.40 | -2.1% |
-| No Fast Digits | 3,041.88 | ±42.60 | 1.40 | **-6.0%** | 23.31 | +1.9% |
-| No Branch Hints | 3,223.95 | ±9.66 | 0.30 | **-0.3%** | 23.11 | +1.0% |
-| Linear Buffer Growth | 3,183.68 | ±39.42 | 1.24 | **-1.6%** | 22.86 | -0.1% |
-
-### Statistical Analysis
-
-**Baseline Performance**:
-- Twitter: 3,235.16 MB/s (±20.78, CV: 0.64%)
-- CITM: 2,278.05 MB/s (±263.44, CV: 11.56%)
-
-**Key Findings**:
-1. Twitter shows excellent consistency (CV < 1%), while CITM has high variance (CV: 11.56%)
-2. Consteval optimization provides ~50% impact for both benchmarks
-3. SIMD optimization: 29.5% impact for Twitter, 19.8% for CITM
-4. Fast digits: minimal impact on Twitter (6%), significant on CITM (24.3%)
-5. Buffer growth: minimal impact on Twitter (1.6%), massive on CITM (40.6%)
-6. Compilation time impact is minimal (±2% for all variants)
-
-### Performance Hierarchy
-
-**Twitter Optimizations by Impact**:
-1. **Tier 1 - Critical (>25% impact)**:
-   - Consteval: 50.2% performance loss when disabled
-   - SIMD Escaping: 29.5% performance loss when disabled
-
-2. **Tier 2 - Moderate (5-10% impact)**:
-   - Fast Digits: 6.0% performance loss when disabled
-
-3. **Tier 3 - Minor (<5% impact)**:
-   - Linear Buffer Growth: 1.6% performance loss when enabled
-   - Branch Hints: 0.3% performance loss when disabled
-
-**CITM Optimizations by Impact**:
-1. **Tier 1 - Critical (>25% impact)**:
-   - Consteval: 51.0% performance loss when disabled
-   - Linear Buffer Growth: 40.6% performance loss when enabled
-
-2. **Tier 2 - Significant (15-25% impact)**:
-   - Fast Digits: 24.3% performance loss when disabled
-   - SIMD Escaping: 19.8% performance loss when disabled
-
-3. **Tier 3 - Moderate (5-15% impact)**:
-   - Branch Hints: 6.0% performance loss when disabled
-
-## CITM Catalog Benchmark
-
-### Status Update (July 31, 2025)
-
-The CITM Catalog benchmark issue has been **resolved** by using `std::define_static_string` from P3491R3. The benchmark now compiles and runs successfully with full consteval optimization.
-
-### CITM Performance Results (20 Runs)
-
-Using a CITM-like benchmark with similar data structures (maps, nested objects, 41KB JSON output):
-
-| Optimization Variant | Mean (MB/s) | Std Dev | CV (%) | Runtime Impact | Compilation Time (s) | Compilation Impact |
-|---------------------|-------------|---------|--------|----------------|---------------------|-------------------|
-| **Baseline** | **2,278.05** | ±263.44 | 11.56 | **Reference** | 22.88 | **Reference** |
-| No Consteval | 1,115.10 | ±38.71 | 3.47 | **-51.0%** | 23.06 | +0.8% |
-| No SIMD Escaping | 1,826.12 | ±26.48 | 1.45 | **-19.8%** | 22.40 | -2.1% |
-| No Fast Digits | 1,723.83 | ±69.55 | 4.03 | **-24.3%** | 23.31 | +1.9% |
-| No Branch Hints | 2,141.79 | ±294.10 | 13.73 | **-6.0%** | 23.11 | +1.0% |
-| Linear Buffer Growth | 1,352.53 | ±52.48 | 3.88 | **-40.6%** | 22.86 | -0.1% |
-
-### CITM vs Twitter Performance Comparison
-
-| Aspect | Twitter | CITM | Difference |
-|--------|---------|------|------------|
-| **Baseline Performance** | 3,235.16 MB/s | 2,278.05 MB/s | CITM is 29.6% slower |
-| **Consteval Impact** | -50.2% | -51.0% | Nearly identical |
-| **SIMD Impact** | -29.5% | -19.8% | 1.5x smaller for CITM |
-| **Fast Digits Impact** | -6.0% | -24.3% | 4x larger for CITM |
-| **Branch Hints Impact** | -0.3% | -6.0% | 20x larger for CITM |
-| **Linear Growth Impact** | -1.6% | -40.6% | 25x larger for CITM |
-
-### Key Findings
-
-1. **Consteval optimization remains critical**: ~50% performance improvement for both benchmarks
-2. **Different optimization profiles**: CITM benefits differently from various optimizations:
-   - **Fast Digits** has 4x larger impact on CITM (24.3% vs 6.0%)
-   - **SIMD Escaping** has 1.5x smaller impact on CITM (19.8% vs 29.5%)
-   - **Branch Hints** has 20x larger impact on CITM (6.0% vs 0.3%)
-   - **Buffer Growth** strategy has 25x larger impact on CITM (40.6% vs 1.6%)
-
-3. **Why the differences?**
-   - **Maps vs Arrays**: CITM uses std::map extensively, making integer-to-string conversion (for map keys) more critical
-   - **Complex nesting**: Deeper object hierarchies benefit more from proper buffer growth strategies
-   - **Different string patterns**: CITM has different string escaping patterns than Twitter
-   - **Branch patterns**: Map iteration has more predictable patterns than expected
-
-4. **Statistical observations with 20 runs**:
-   - CITM variance reduced from 19.09% to 11.56% with more runs
-   - Twitter maintains excellent consistency (CV: 0.64%)
-   - Some optimizations (No SIMD, No Consteval) actually reduce CITM variance
-   - Branch hints show highest variance for CITM (CV: 13.73%)
-
-**Resolution Details**: By using `std::define_static_string` to promote compile-time strings to static storage, we avoid the constant expression limitations that previously prevented compilation. The threshold workaround is no longer needed. See `citm_issue.md` for technical details.
-
-## Conclusions
-
-1. **Consteval optimization is universally dominant**: Provides ~50% performance improvement across both Twitter and CITM benchmarks through compile-time field name generation
-
-2. **Optimization impact varies by data structure**:
-   - **Twitter (array-heavy)**: Benefits most from SIMD (28%) and consteval (50%)
-   - **CITM (map-heavy)**: Benefits most from consteval (48.5%), fast digits (32.7%), and buffer growth (33.4%)
-
-3. **Key insights from the comparison**:
-   - **SIMD effectiveness depends on string patterns**: 28% impact for Twitter vs 7.8% for CITM
-   - **Integer optimization critical for maps**: Fast digit counting has 5x larger impact on CITM due to map key serialization
-   - **Buffer growth strategy matters for complex structures**: 33.4% impact for CITM's nested maps vs 1.8% for Twitter's arrays
-   - **Branch prediction can backfire**: CITM performs 9.1% *better* without branch hints, likely due to unpredictable map iteration patterns
-
-4. **Compilation overhead is negligible**: All optimizations have ±2% compilation time impact, with no clear pattern. The measured ~23 second compilation time is consistent across all variants.
-
-5. **Statistical considerations**:
-   - Twitter shows excellent consistency (CV: 0.64%)
-   - CITM shows higher variance (CV: 11.56% with 20 runs, down from 19.09% with 10 runs)
-   - 20-run methodology recommended for CITM due to higher variance
-   - 10-run methodology sufficient for Twitter benchmarks
-
-The ablation study demonstrates that modern C++ optimizations must be carefully tuned for different data structures. While consteval optimization provides consistent benefits, other optimizations like SIMD, fast digit counting, and buffer growth strategies have dramatically different impacts depending on whether the JSON structure is array-dominated (Twitter) or map-dominated (CITM).

benchmark/CMakeLists.txt

@@ -1,9 +1,10 @@
 add_subdirectory(dom)
 
 
-include_directories( . linux )
+include_directories( . )
 link_libraries(simdjson-windows-headers test-data)
 link_libraries(simdjson)
+link_libraries(counters)
 if(SIMDJSON_STATIC_REFLECTION)
   add_compile_definitions(SIMDJSON_STATIC_REFLECTION=1)
 endif(SIMDJSON_STATIC_REFLECTION)
@@ -15,6 +16,7 @@ if (TARGET benchmark::benchmark)
   link_libraries(benchmark::benchmark)
   add_executable(bench_parse_call bench_parse_call.cpp)
   add_executable(bench_dom_api bench_dom_api.cpp)
+  add_executable(bench_stream_formats bench_stream_formats.cpp)
   if(SIMDJSON_EXCEPTIONS)
     add_executable(bench_ondemand bench_ondemand.cpp)
     if(TARGET yyjson)

benchmark/UNIFIED_RESULTS.md

@@ -1,203 +0,0 @@
-# Unified Benchmark Results - JSON Parsing Performance
-
-## Overview
-
-Comparison of simdjson's C++26 static reflection implementation against traditional JSON libraries for parsing performance (JSON → C++ structs).
-
-## Test Environment
-
-- **Compiler**: bloomberg/clang-p2996 (C++26 with reflection support)
-- **Platform**: Linux aarch64
-- **Build Type**: Release with -O3
-- **Methodology**: Conservative approach - fresh parser instance per iteration
-- **Date**: September 2025
-
-## Parsing Performance Results
-
-### Twitter Parsing Benchmark (631KB, String-Heavy)
-
-| Library/Method | Throughput | Latency | Speedup vs nlohmann |
-|----------------|------------|---------|-------------------|
-| **simdjson (manual)** | 4362.9 MB/s | 138.04 μs | 25.4x |
-| **simdjson (reflection)** | 4091.7 MB/s | 147.19 μs | 23.8x |
-| **simdjson::from()** | 4169.3 MB/s | 144.45 μs | 24.2x |
-| nlohmann (extraction) | 172.0 MB/s | 3501.02 μs | 1.0x (baseline) |
-| RapidJSON (extraction) | 658.1 MB/s | 915.14 μs | 3.8x |
-| Serde (Rust) | 1722.0 MB/s | 349.75 μs | 10.0x |
-| yyjson | 2233.0 MB/s | 269.71 μs | 13.0x |
-
-### CITM Catalog Parsing Benchmark (1.7MB, Complex Objects)
-
-| Library/Method | Throughput | Latency | Speedup vs nlohmann |
-|----------------|------------|---------|-------------------|
-| **simdjson (manual)** | 3013.7 MB/s | 546.57 μs | 16.2x |
-| **simdjson (reflection)** | 2656.4 MB/s | 620.07 μs | 14.3x |
-| **simdjson::from()** | 2669.5 MB/s | 617.03 μs | 14.4x |
-| nlohmann (extraction) | 185.6 MB/s | 8874.02 μs | 1.0x (baseline) |
-| RapidJSON (extraction) | 1216.0 MB/s | 1354.62 μs | 6.5x |
-| Serde (Rust) | 534.6 MB/s | 3081.24 μs | 2.9x |
-| yyjson | 2681.3 MB/s | 614.32 μs | 14.4x |
-
-## Key Findings
-
-1. **Reflection performs excellently**: Only 6-13% slower than manual implementation
-2. **Massive speedup over traditional libraries**: 14-25x faster than nlohmann::json
-3. **Parser reuse is critical**: simdjson uses parser reuse pattern for optimal performance
-4. **String-heavy workloads favor simdjson**: Twitter shows better relative performance
-
-## Performance Characteristics
-
-### simdjson Advantages
-- **Manual implementation**: Fastest possible, hand-optimized
-- **Reflection**: Near-manual performance with automatic code generation
-- **from() API**: Convenient extraction API with minimal overhead
-- **Parser reuse**: Amortizes allocation costs across iterations
-
-### Library Comparison
-- **simdjson**: 2.7-4.4 GB/s throughput (conservative approach)
-- **yyjson**: 2.2-2.7 GB/s throughput (comparable performance)
-- **Serde (Rust)**: 0.5-1.7 GB/s throughput (2.4-5.6x slower)
-- **RapidJSON**: 0.7-1.2 GB/s throughput (3.6-6.5x slower)
-- **nlohmann**: 172-186 MB/s throughput (14-25x slower)
-
-## Implementation Notes
-
-- **Conservative approach**: Fresh parser instance per iteration (realistic usage)
-- **Reflection implementation**: Uses C++26 static reflection (P2996)
-- **Compilation**: Standalone with -O3 optimization
-- **Results**: Median of 500-1000 iterations
-
-### Performance Difference vs Ablation Study
-
-The unified benchmark shows ~15% higher throughput (3.7 vs 3.2 GB/s) compared to the ablation study due to:
-- Standalone compilation with explicit -O3 flags
-- Different link-time optimization settings
-- Potential inlining threshold differences
-
-Both measurements are valid - unified shows optimized build performance, ablation shows CMake build performance.
-
-## Conclusion
-
-simdjson's C++26 static reflection provides:
-- **Near-manual performance** (within 6-13%)
-- **14-25x speedup** over nlohmann::json
-- **2.4-5.6x speedup** over Serde (Rust)
-- **3.6-6.5x speedup** over RapidJSON
-- **Automatic code generation** with reflection
-
-This demonstrates that C++26 reflection can provide zero-cost abstractions for JSON parsing.
-
-## Serialization Performance Results
-
-### Twitter Serialization Benchmark (631KB, String-Heavy)
-
-| Library/Method | Throughput | Latency | Speedup vs nlohmann |
-|----------------|------------|---------|-------------------|
-| **simdjson (reflection)** | 3521.5 MB/s | 23.00 μs | 14.5x |
-| **simdjson (DOM)** | 1674.3 MB/s | 48.36 μs | 6.9x |
-| nlohmann::json | 242.3 MB/s | 334.18 μs | 1.0x (baseline) |
-| RapidJSON | 861.1 MB/s | 94.04 μs | 3.6x |
-| yyjson | 2079.4 MB/s | 38.94 μs | 8.6x |
-| Serde (Rust) | 1321.5 MB/s | 61.28 μs | 5.5x |
-
-### CITM Catalog Serialization Benchmark (1.7MB, Complex Objects)
-
-| Library/Method | Throughput | Latency | Speedup vs nlohmann |
-|----------------|------------|---------|-------------------|
-| **simdjson (reflection)** | 2250.0 MB/s | 212.06 μs | 18.1x |
-| **simdjson (DOM)** | 779.6 MB/s | 612.03 μs | 6.3x |
-| nlohmann::json | 124.5 MB/s | 3831.37 μs | 1.0x (baseline) |
-| RapidJSON | 353.5 MB/s | 1349.76 μs | 2.8x |
-| yyjson | 1665.7 MB/s | 286.43 μs | 13.4x |
-| Serde (Rust) | 1167.1 MB/s | 408.82 μs | 9.4x |
-
-## Serialization Ablation Study Results
-
-### Impact of Compiler Optimizations on Serialization Performance
-
-The ablation study disabled individual optimizations to measure their contribution:
-
-#### Twitter Dataset (631KB)
-
-| Variant | Throughput | Performance Impact |
-|---------|------------|-----------------|
-| **Baseline** | 3211.1 MB/s | 100% (reference) |
-| No consteval | 1607.4 MB/s | -50.0% |
-| No SIMD escaping | 2269.2 MB/s | -29.3% |
-| No fast digits | 3034.8 MB/s | -5.5% |
-| No branch hints | 3182.5 MB/s | -0.9% |
-| Linear growth | 3225.4 MB/s | +0.4% |
-
-#### CITM Dataset (1.7MB)
-
-| Variant | Throughput | Performance Impact |
-|---------|------------|-----------------|
-| **Baseline** | 2360.1 MB/s | 100% (reference) |
-| No consteval | 978.3 MB/s | -58.6% |
-| No SIMD escaping | 2259.0 MB/s | -4.3% |
-| No fast digits | 1766.8 MB/s | -25.1% |
-| No branch hints | 2247.4 MB/s | -4.8% |
-| Linear growth | 2289.9 MB/s | -3.0% |
-
-### Key Findings from Ablation Study
-
-1. **consteval is critical**: Disabling compile-time evaluation reduces performance by 50-59%
-2. **SIMD escaping provides significant boost**: 4-29% performance improvement for string escaping
-3. **Fast digit conversion matters**: Especially for number-heavy datasets (25% improvement on CITM)
-4. **Branch hints have minimal impact**: Less than 5% difference in most cases
-5. **Exponential growth strategy**: Shows slight benefit over linear (3-4% improvement)
-
-## Running Benchmarks with Serde Comparison
-
-### Serialization Benchmarks (Including Serde)
-
-The repository includes benchmarks comparing simdjson with Serde (Rust's serialization framework).
-
-#### Prerequisites
-- Rust and Cargo installed (`curl https://sh.rustup.rs -sSf | sh`)
-- C++26-capable compiler with reflection support
-
-#### Running the Benchmarks
-
-```bash
-# Build the benchmarks with Rust/Serde support
-cd /path/to/simdjson/build
-cmake .. -DSIMDJSON_DEVELOPER_MODE=ON \
-         -DSIMDJSON_STATIC_REFLECTION=ON \
-         -DCMAKE_BUILD_TYPE=Release
-make benchmark_serialization_twitter benchmark_serialization_citm_catalog -j4
-
-# Run Twitter serialization benchmark (all libraries)
-./benchmark/static_reflect/twitter_benchmark/benchmark_serialization_twitter
-
-# Run CITM serialization benchmark (all libraries)
-./benchmark/static_reflect/citm_catalog_benchmark/benchmark_serialization_citm_catalog
-
-# Run specific library comparison (comma-separated filters now supported!)
-./benchmark/static_reflect/twitter_benchmark/benchmark_serialization_twitter -f simdjson_static_reflection,simdjson_to,rust
-
-# List available benchmarks
-./benchmark/static_reflect/twitter_benchmark/benchmark_serialization_twitter -l
-```
-
-#### Expected Results
-
-**Twitter Dataset (631KB) - Latest Results**
-- simdjson (reflection): 3.52 GB/s
-- yyjson: 2.08 GB/s
-- simdjson (DOM): 1.67 GB/s
-- Serde (Rust): 1.32 GB/s
-- RapidJSON: 0.86 GB/s
-- nlohmann: 0.24 GB/s
-
-**CITM Dataset (1.7MB) - Latest Results**
-- simdjson (reflection): 2.25 GB/s
-- yyjson: 1.67 GB/s
-- Serde (Rust): 1.17 GB/s
-- simdjson (DOM): 0.78 GB/s
-- RapidJSON: 0.35 GB/s
-- nlohmann: 0.12 GB/s
-
-**Key Finding**: simdjson with C++26 reflection achieves 1.8-1.9x faster serialization than Serde.
-
-Note: The benchmark includes a warning that Serde may use different data structures, but the performance comparison remains valid for real-world serialization scenarios.

benchmark/bench_ondemand.cpp

@@ -124,6 +124,7 @@ SIMDJSON_POP_DISABLE_WARNINGS
 #include "kostya/boostjson.h"
 
 #include "large_random/simdjson_ondemand.h"
+#include "large_random/simdjson_ondemand_ranges.h"
 #if SIMDJSON_COMPETITION_ONDEMAND_UNORDERED
 #include "large_random/simdjson_ondemand_unordered.h"
 #endif // SIMDJSON_COMPETITION_ONDEMAND_UNORDERED

benchmark/bench_stream_formats.cpp

@@ -0,0 +1,216 @@
+#include <benchmark/benchmark.h>
+#include <string>
+#include "simdjson.h"
+
+using namespace simdjson;
+
+namespace {
+
+enum class stream_case {
+  ndjson_small,
+  ndjson_large,
+  rfc7464_small,
+  rfc7464_large,
+  comma_delimited_small,
+  comma_delimited_large
+};
+
+constexpr size_t TARGET_BYTES = 128 * 1000 * 1000;
+constexpr size_t SMALL_PAYLOAD = 16;
+constexpr size_t LARGE_PAYLOAD = 4096;
+constexpr size_t BATCH_SIZE = 1 << 20;
+
+struct stream_dataset {
+  padded_string json;
+  size_t count{};
+};
+
+std::string make_document(size_t id, size_t payload_size) {
+  return std::string{"{\"id\":"} + std::to_string(id) +
+    ",\"name\":\"aaaaaaaa\",\"payload\":\"" +
+    std::string(payload_size, 'x') + "\",\"flag\":true}";
+}
+
+stream_dataset build_dataset(stream_case which) {
+  const bool small = which == stream_case::ndjson_small ||
+                     which == stream_case::rfc7464_small ||
+                     which == stream_case::comma_delimited_small;
+  const bool rfc = which == stream_case::rfc7464_small ||
+                   which == stream_case::rfc7464_large;
+  const bool comma = which == stream_case::comma_delimited_small ||
+                     which == stream_case::comma_delimited_large;
+  const size_t payload_size = small ? SMALL_PAYLOAD : LARGE_PAYLOAD;
+  const size_t count = TARGET_BYTES / (payload_size + 48);
+  std::string out;
+  out.reserve(count * (payload_size + 64));
+  for (size_t i = 0; i < count; i++) {
+    if (rfc) {
+      out += char(0x1E);
+    }
+    if (comma && i > 0) {
+      out += ',';
+    }
+    out += make_document(i, payload_size);
+    if (!comma) {
+      out += '\n';
+    }
+  }
+  return {padded_string(out), count};
+}
+
+const stream_dataset &get_dataset(stream_case which) {
+  static const stream_dataset ndjson_small =
+    build_dataset(stream_case::ndjson_small);
+  static const stream_dataset ndjson_large =
+    build_dataset(stream_case::ndjson_large);
+  static const stream_dataset rfc_small =
+    build_dataset(stream_case::rfc7464_small);
+  static const stream_dataset rfc_large =
+    build_dataset(stream_case::rfc7464_large);
+  static const stream_dataset comma_small =
+    build_dataset(stream_case::comma_delimited_small);
+  static const stream_dataset comma_large =
+    build_dataset(stream_case::comma_delimited_large);
+  switch (which) {
+    case stream_case::ndjson_small:
+      return ndjson_small;
+    case stream_case::ndjson_large:
+      return ndjson_large;
+    case stream_case::rfc7464_small:
+      return rfc_small;
+    case stream_case::rfc7464_large:
+      return rfc_large;
+    case stream_case::comma_delimited_small:
+      return comma_small;
+    case stream_case::comma_delimited_large:
+      return comma_large;
+  }
+  return ndjson_small;
+}
+
+void set_counters(benchmark::State &state, const stream_dataset &dataset) {
+  state.SetBytesProcessed(int64_t(state.iterations()) * int64_t(dataset.json.size()));
+  state.SetItemsProcessed(int64_t(state.iterations()) * int64_t(dataset.count));
+}
+
+template <stream_case which, bool threaded = true>
+static void bench_ondemand(benchmark::State &state) {
+  const auto &dataset = get_dataset(which);
+  ondemand::parser parser;
+  parser.threaded = threaded;
+  stream_format format = stream_format::whitespace_delimited;
+  if constexpr (which == stream_case::rfc7464_small ||
+                which == stream_case::rfc7464_large) {
+    format = stream_format::json_sequence;
+  } else if constexpr (which == stream_case::comma_delimited_small ||
+                       which == stream_case::comma_delimited_large) {
+    format = stream_format::comma_delimited;
+  }
+  for (const auto _ : state) {
+    ondemand::document_stream docs;
+    auto error = parser.iterate_many(dataset.json, BATCH_SIZE, format).get(docs);
+    if (error) {
+      state.SkipWithError(error_message(error));
+      return;
+    }
+    uint64_t sum = 0;
+    for (auto doc : docs) {
+      ondemand::object obj;
+      if ((error = doc.get_object().get(obj))) {
+        state.SkipWithError(error_message(error));
+        return;
+      }
+      uint64_t id;
+      if ((error = obj["id"].get_uint64().get(id))) {
+        state.SkipWithError(error_message(error));
+        return;
+      }
+      sum += id;
+    }
+    benchmark::DoNotOptimize(sum);
+  }
+  set_counters(state, dataset);
+}
+
+template <stream_case which>
+static void bench_dom(benchmark::State &state) {
+  const auto &dataset = get_dataset(which);
+  dom::parser parser;
+  parser.threaded = true;
+  stream_format format = stream_format::whitespace_delimited;
+  if constexpr (which == stream_case::rfc7464_small ||
+                which == stream_case::rfc7464_large) {
+    format = stream_format::json_sequence;
+  } else if constexpr (which == stream_case::comma_delimited_small ||
+                       which == stream_case::comma_delimited_large) {
+    format = stream_format::comma_delimited;
+  }
+  for (const auto _ : state) {
+    dom::document_stream docs;
+    auto error = parser.parse_many(dataset.json, BATCH_SIZE, format).get(docs);
+    if (error) {
+      state.SkipWithError(error_message(error));
+      return;
+    }
+    uint64_t sum = 0;
+    for (auto doc : docs) {
+      uint64_t id;
+      if ((error = doc["id"].get(id))) {
+        state.SkipWithError(error_message(error));
+        return;
+      }
+      sum += id;
+    }
+    benchmark::DoNotOptimize(sum);
+  }
+  set_counters(state, dataset);
+}
+
+} // namespace
+
+BENCHMARK(bench_ondemand<stream_case::ndjson_small>)
+    ->UseRealTime()
+    ->DisplayAggregatesOnly(true);
+BENCHMARK(bench_ondemand<stream_case::ndjson_large>)
+    ->UseRealTime()
+    ->DisplayAggregatesOnly(true);
+BENCHMARK(bench_ondemand<stream_case::rfc7464_small>)
+    ->UseRealTime()
+    ->DisplayAggregatesOnly(true);
+BENCHMARK(bench_ondemand<stream_case::rfc7464_large>)
+    ->UseRealTime()
+    ->DisplayAggregatesOnly(true);
+BENCHMARK(bench_ondemand<stream_case::comma_delimited_small>)
+    ->UseRealTime()
+    ->DisplayAggregatesOnly(true);
+BENCHMARK(bench_ondemand<stream_case::comma_delimited_large>)
+    ->UseRealTime()
+    ->DisplayAggregatesOnly(true);
+// Non-threaded comma_delimited for comparison
+BENCHMARK(bench_ondemand<stream_case::comma_delimited_small, false>)
+    ->UseRealTime()
+    ->DisplayAggregatesOnly(true);
+BENCHMARK(bench_ondemand<stream_case::comma_delimited_large, false>)
+    ->UseRealTime()
+    ->DisplayAggregatesOnly(true);
+
+BENCHMARK(bench_dom<stream_case::ndjson_small>)
+    ->UseRealTime()
+    ->DisplayAggregatesOnly(true);
+BENCHMARK(bench_dom<stream_case::ndjson_large>)
+    ->UseRealTime()
+    ->DisplayAggregatesOnly(true);
+BENCHMARK(bench_dom<stream_case::rfc7464_small>)
+    ->UseRealTime()
+    ->DisplayAggregatesOnly(true);
+BENCHMARK(bench_dom<stream_case::rfc7464_large>)
+    ->UseRealTime()
+    ->DisplayAggregatesOnly(true);
+BENCHMARK(bench_dom<stream_case::comma_delimited_small>)
+    ->UseRealTime()
+    ->DisplayAggregatesOnly(true);
+BENCHMARK(bench_dom<stream_case::comma_delimited_large>)
+    ->UseRealTime()
+    ->DisplayAggregatesOnly(true);
+
+BENCHMARK_MAIN();

benchmark/benchfeatures.cpp

@@ -1,4 +1,5 @@
-#include "event_counter.h"
+#include <counters/event_counter.h>
+using namespace counters;
 
 #include <cassert>
 #include <cctype>
@@ -25,7 +26,6 @@
 #include <string>
 #include <vector>
 
-#include "linux-perf-events.h"
 #ifdef __linux__
 #include <libgen.h>
 #endif
@@ -204,12 +204,8 @@ struct feature_benchmarker {
   }
   // Rate of 1-7-structural misses per 8-structural flip
   double struct1_7_miss_rate(BenchmarkStage stage) const {
-#if SIMDJSON_SIMPLE_PERFORMANCE_COUNTERS
-    return 1;
-#else
     if (!has_events()) { return 1; }
     return struct7_miss[stage].best.branch_misses() - struct7[stage].best.branch_misses() / double(struct7_miss.stats->blocks_with_1_structural_flipped);
-#endif
   }
   // Extra cost of an 8-15 structural block over a 1-7 structural block
   double struct8_15_cost(BenchmarkStage stage) const {
@@ -221,12 +217,8 @@ struct feature_benchmarker {
   }
   // Rate of 8-15-structural misses per 8-structural flip
   double struct8_15_miss_rate(BenchmarkStage stage) const {
-#if SIMDJSON_SIMPLE_PERFORMANCE_COUNTERS
-    return 1;
-#else
     if (!has_events()) { return 1; }
     return double(struct15_miss[stage].best.branch_misses() - struct15[stage].best.branch_misses()) / double(struct15_miss.stats->blocks_with_8_structurals_flipped);
-#endif
   }
 
   // Extra cost of a 16+-structural block over an 8-15 structural block (actual varies based on # of structurals!)
@@ -239,12 +231,8 @@ struct feature_benchmarker {
   }
   // Rate of 16-structural misses per 16-structural flip
   double struct16_miss_rate(BenchmarkStage stage) const {
-#if SIMDJSON_SIMPLE_PERFORMANCE_COUNTERS
-    return 1;
-#else
     if (!has_events()) { return 1; }
     return double(struct23_miss[stage].best.branch_misses() - struct23[stage].best.branch_misses()) / double(struct23_miss.stats->blocks_with_16_structurals_flipped);
-#endif
   }
 
 
@@ -258,12 +246,8 @@ struct feature_benchmarker {
   }
   // Rate of UTF-8 misses per UTF-8 flip
   double utf8_miss_rate(BenchmarkStage stage) const {
-#if SIMDJSON_SIMPLE_PERFORMANCE_COUNTERS
-    return 1;
-#else
     if (!has_events()) { return 1; }
     return double(utf8_miss[stage].best.branch_misses() - utf8[stage].best.branch_misses()) / double(utf8_miss.stats->blocks_with_utf8_flipped);
-#endif
   }
   // Extra cost of having escapes in a block
   double escape_cost(BenchmarkStage stage) const {
@@ -275,12 +259,8 @@ struct feature_benchmarker {
   }
   // Rate of escape misses per escape flip
   double escape_miss_rate(BenchmarkStage stage) const {
-#if SIMDJSON_SIMPLE_PERFORMANCE_COUNTERS
-    return 1;
-#else
     if (!has_events()) { return 1; }
     return double(escape_miss[stage].best.branch_misses() - escape[stage].best.branch_misses()) / double(escape_miss.stats->blocks_with_escapes_flipped);
-#endif
   }
 
 
@@ -378,22 +358,6 @@ struct feature_benchmarker {
   }
 };
 
-#if SIMDJSON_SIMPLE_PERFORMANCE_COUNTERS
-void print_file_effectiveness(BenchmarkStage stage, const char* filename, const benchmarker& results, const feature_benchmarker& features) {
-  double actual = results[stage].best.elapsed_ns() / double(results.stats->blocks);
-  double calc = features.calc_expected(stage, results);
-  double calc_misses = features.calc_expected_misses(stage, results);
-  double calc_miss_cost = features.calc_expected_miss_cost(stage, results);
-  printf("        | %-8s ", benchmark_stage_name(stage));
-  printf("| %-15s ",   filename);
-  printf("|    %8.3g ", features.calc_expected_feature_cost(stage, results));
-  printf("|    %8.3g ", calc_miss_cost);
-  printf("| %8.3g ",  calc);
-  printf("| %8.3g ",  actual);
-  printf("| %+8.3g ", actual - calc);
-  printf("| %13llu ", (long long unsigned)(calc_misses));
-}
-#else
 void print_file_effectiveness(BenchmarkStage stage, const char* filename, const benchmarker& results, const feature_benchmarker& features) {
   double actual = results[stage].best.elapsed_ns() / double(results.stats->blocks);
   double calc = features.calc_expected(stage, results);
@@ -417,7 +381,6 @@ void print_file_effectiveness(BenchmarkStage stage, const char* filename, const
   }
   printf("|\n");
 }
-#endif
 
 int main(int argc, char *argv[]) {
   // Read options

benchmark/benchmark.h

@@ -1,7 +1,8 @@
 #ifndef _BENCHMARK_H_
 #define _BENCHMARK_H_
 
-#include "event_counter.h"
+#include <counters/event_counter.h>
+using namespace counters;
 
 /*
  * Prints the best number of operations per cycle where

benchmark/benchmarker.h

@@ -1,7 +1,8 @@
 #ifndef __BENCHMARKER_H
 #define __BENCHMARKER_H
 
-#include "event_counter.h"
+#include <counters/event_counter.h>
+using namespace counters;
 #include "simdjson.h"
 
 #include <cassert>
@@ -28,11 +29,9 @@
 #include <string>
 #include <vector>
 
-#include "linux-perf-events.h"
 #ifdef __linux__
 #include <libgen.h>
 #endif
-#include "simdjson.h"
 
 #include <functional>
 
@@ -423,18 +422,12 @@ struct benchmarker {
         stage.instructions() / static_cast<double>(stats->structurals),
         stage.instructions() / static_cast<double>(stage.cycles())
       );
-#if !SIMDJSON_SIMPLE_PERFORMANCE_COUNTERS
-      // NOTE: removed cycles/miss because it is a somewhat misleading stat
-      printf("%s%-13s: %7.0f branch misses (%6.2f%%) - %.0f cache misses (%6.2f%%) - %.2f cache references\n",
+      printf("%s%-13s: %7.0f branch misses (%6.2f%%)\n",
         prefix,
         "Misses",
         stage.branch_misses(),
-        percent(stage.branch_misses(), all_stages_without_allocation.branch_misses()),
-        stage.cache_misses(),
-        percent(stage.cache_misses(), all_stages_without_allocation.cache_misses()),
-        stage.cache_references()
+        percent(stage.branch_misses(), all_stages_without_allocation.branch_misses())
       );
-#endif
     }
   }
 

benchmark/build_unified_benchmark.sh

@@ -1,95 +0,0 @@
-#!/bin/bash
-
-# Build script for the unified benchmark
-# Automatically detects available libraries and builds accordingly
-
-set -e
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-ROOT_DIR="$(dirname "$SCRIPT_DIR")"
-BUILD_DIR="$ROOT_DIR/build"
-
-echo "=== Building Unified JSON Benchmark ==="
-echo ""
-
-# Check for clang++ with C++26 support
-if ! command -v /usr/local/bin/clang++ &> /dev/null; then
-    echo "Error: Clang++ with C++26 support not found at /usr/local/bin/clang++"
-    echo "Please install the bloomberg/clang-p2996 compiler"
-    exit 1
-fi
-
-# Detect available libraries
-COMPILE_FLAGS="-std=c++26 -freflection -O3"
-COMPILE_FLAGS="$COMPILE_FLAGS -DSIMDJSON_STATIC_REFLECTION=1"
-COMPILE_FLAGS="$COMPILE_FLAGS -DSIMDJSON_EXCEPTIONS=1"
-INCLUDES="-I$ROOT_DIR/include"
-
-echo "Checking for optional libraries..."
-
-# Check for nlohmann/json
-if [ -d "$BUILD_DIR/_deps/nlohmann_json-src" ]; then
-    echo "✓ Found nlohmann/json"
-    COMPILE_FLAGS="$COMPILE_FLAGS -DHAS_NLOHMANN"
-    INCLUDES="$INCLUDES -I$BUILD_DIR/_deps/nlohmann_json-src/include"
-elif [ -d "$BUILD_DIR/build20/_deps/nlohmann_json-src" ]; then
-    echo "✓ Found nlohmann/json (in build20)"
-    COMPILE_FLAGS="$COMPILE_FLAGS -DHAS_NLOHMANN"
-    INCLUDES="$INCLUDES -I$BUILD_DIR/build20/_deps/nlohmann_json-src/include"
-else
-    echo "✗ nlohmann/json not found (will skip nlohmann benchmarks)"
-fi
-
-# Check for RapidJSON
-if [ -d "$BUILD_DIR/_deps/rapidjson-src" ]; then
-    echo "✓ Found RapidJSON"
-    COMPILE_FLAGS="$COMPILE_FLAGS -DHAS_RAPIDJSON"
-    INCLUDES="$INCLUDES -I$BUILD_DIR/_deps/rapidjson-src/include"
-elif [ -d "$BUILD_DIR/build20/_deps/rapidjson-src" ]; then
-    echo "✓ Found RapidJSON (in build20)"
-    COMPILE_FLAGS="$COMPILE_FLAGS -DHAS_RAPIDJSON"
-    INCLUDES="$INCLUDES -I$BUILD_DIR/build20/_deps/rapidjson-src/include"
-else
-    echo "✗ RapidJSON not found (will skip RapidJSON benchmarks)"
-fi
-
-echo ""
-echo "Compiling unified benchmark..."
-
-# Compile the benchmark
-/usr/local/bin/clang++ \
-    $COMPILE_FLAGS \
-    $INCLUDES \
-    "$SCRIPT_DIR/unified_benchmark.cpp" \
-    "$ROOT_DIR/singleheader/simdjson.cpp" \
-    -o "$SCRIPT_DIR/unified_benchmark"
-
-if [ $? -eq 0 ]; then
-    echo ""
-    echo "✓ Build successful!"
-    echo ""
-    echo "Running benchmark..."
-    echo "==================="
-    echo ""
-
-    # Run the benchmark from the correct directory
-    cd "$ROOT_DIR"
-    "$SCRIPT_DIR/unified_benchmark"
-
-    if [ $? -eq 0 ]; then
-        echo ""
-        echo "✓ Benchmark completed successfully!"
-    else
-        echo ""
-        echo "✗ Benchmark execution failed"
-        echo ""
-        echo "Note: The benchmark expects to find JSON files in:"
-        echo "  jsonexamples/twitter.json"
-        echo "  jsonexamples/citm_catalog.json"
-        exit 1
-    fi
-else
-    echo ""
-    echo "✗ Build failed"
-    exit 1
-fi

benchmark/car_builder/benchmark_car_builder.cpp

@@ -1,4 +1,5 @@
-#include "event_counter.h"
+#include <counters/event_counter.h>
+using namespace counters;
 #include <random>
 #include <vector>
 

benchmark/dom/CMakeLists.txt

@@ -1,11 +1,12 @@
-include_directories( .. ../linux )
+include_directories( .. )
 link_libraries(simdjson-windows-headers test-data)
 link_libraries(simdjson)
+link_libraries(counters)
 
 add_executable(perfdiff perfdiff.cpp)
 add_executable(parse parse.cpp)
 add_executable(parse_stream parse_stream.cpp)
-add_executable(statisticalmodel statisticalmodel.cpp)
+
 
 add_executable(parse_noutf8validation parse.cpp)
 target_compile_definitions(parse_noutf8validation PRIVATE SIMDJSON_SKIPUTF8VALIDATION)

benchmark/dom/parse.cpp

@@ -1,4 +1,5 @@
-#include "event_counter.h"
+#include <counters/event_counter.h>
+using namespace counters;
 
 #include <cassert>
 #include <cctype>
@@ -24,7 +25,6 @@
 #include <string>
 #include <vector>
 
-#include "linux-perf-events.h"
 #ifdef __linux__
 #include <libgen.h>
 #endif

benchmark/dom/statisticalmodel.cpp

@@ -1,207 +0,0 @@
-#include <iostream>
-#include <unistd.h>
-#include "simdjson.h"
-#ifdef __linux__
-#include "linux-perf-events.h"
-#endif
-
-size_t count_nonasciibytes(const uint8_t *input, size_t length) {
-  size_t count = 0;
-  for (size_t i = 0; i < length; i++) {
-    count += input[i] >> 7;
-  }
-  return count;
-}
-
-size_t count_backslash(const uint8_t *input, size_t length) {
-  size_t count = 0;
-  for (size_t i = 0; i < length; i++) {
-    count += (input[i] == '\\') ? 1 : 0;
-  }
-  return count;
-}
-
-struct stat_s {
-  size_t integer_count;
-  size_t float_count;
-  size_t string_count;
-  size_t backslash_count;
-  size_t non_ascii_byte_count;
-  size_t object_count;
-  size_t array_count;
-  size_t null_count;
-  size_t true_count;
-  size_t false_count;
-  size_t byte_count;
-  size_t structural_indexes_count;
-  bool valid;
-};
-
-using stat_t = struct stat_s;
-
-
-
-simdjson_inline void simdjson_process_atom(stat_t &s,
-                                         simdjson::dom::element element) {
-  if (element.is<int64_t>()) {
-    s.integer_count++;
-  } else if(element.is<std::string_view>()) {
-    s.string_count++;
-  } else if(element.is<double>()) {
-    s.float_count++;
-  } else if (element.is<bool>()) {
-    bool v;
-    simdjson::error_code error;
-    if ((error = element.get(v))) { std::cerr << error << std::endl; abort(); }
-    if (v) {
-      s.true_count++;
-    } else {
-      s.false_count++;
-    }
-  } else if (element.is_null()) {
-    s.null_count++;
-  }
-}
-
-void simdjson_recurse(stat_t &s, simdjson::dom::element element) {
-  simdjson::error_code error;
-  if (element.is<simdjson::dom::array>()) {
-    s.array_count++;
-    simdjson::dom::array array;
-    if ((error = element.get(array))) { std::cerr << error << std::endl; abort(); }
-    for (auto child : array) {
-      if (child.is<simdjson::dom::array>() || child.is<simdjson::dom::object>()) {
-        simdjson_recurse(s, child);
-      } else {
-        simdjson_process_atom(s, child);
-      }
-    }
-  } else if (element.is<simdjson::dom::object>()) {
-    s.object_count++;
-    simdjson::dom::object object;
-    if ((error = element.get(object))) { std::cerr << error << std::endl; abort(); }
-    for (auto field : object) {
-      s.string_count++; // for key
-      if (field.value.is<simdjson::dom::array>() || field.value.is<simdjson::dom::object>()) {
-        simdjson_recurse(s, field.value);
-      } else {
-        simdjson_process_atom(s, field.value);
-      }
-    }
-  } else {
-    simdjson_process_atom(s, element);
-  }
-}
-
-stat_t simdjson_compute_stats(const simdjson::padded_string &p) {
-  stat_t answer{};
-  simdjson::dom::parser parser;
-  simdjson::dom::element doc;
-  auto error = parser.parse(p).get(doc);
-  if (error) {
-    answer.valid = false;
-    return answer;
-  }
-  answer.valid = true;
-  answer.backslash_count =
-      count_backslash(reinterpret_cast<const uint8_t *>(p.data()), p.size());
-  answer.non_ascii_byte_count = count_nonasciibytes(
-      reinterpret_cast<const uint8_t *>(p.data()), p.size());
-  answer.byte_count = p.size();
-  answer.structural_indexes_count = parser.implementation->n_structural_indexes;
-  simdjson_recurse(answer, doc);
-  return answer;
-}
-
-int main(int argc, char *argv[]) {
-#ifndef _MSC_VER
-  int c;
-  while ((c = getopt(argc, argv, "")) != -1) {
-    switch (c) {
-
-    default:
-      abort();
-    }
-  }
-#else
-  int optind = 1;
-#endif
-  if (optind >= argc) {
-    std::cerr << "Reads json, prints stats. " << std::endl;
-    std::cerr << "Usage: " << argv[0] << " <jsonfile>" << std::endl;
-
-    exit(1);
-  }
-  const char *filename = argv[optind];
-  if (optind + 1 < argc) {
-    std::cerr << "warning: ignoring everything after " << argv[optind + 1]
-              << std::endl;
-  }
-  simdjson::padded_string p;
-  auto error = simdjson::padded_string::load(filename).get(p);
-  if (error) {
-    std::cerr << "Could not load the file " << filename << std::endl;
-    return EXIT_FAILURE;
-  }
-  stat_t s = simdjson_compute_stats(p);
-  if (!s.valid) {
-    std::cerr << "not a valid JSON" << std::endl;
-    return EXIT_FAILURE;
-  }
-
-  printf("# integer_count float_count string_count backslash_count "
-         "non_ascii_byte_count object_count array_count null_count true_count "
-         "false_count byte_count structural_indexes_count ");
-#ifdef __linux__
-  printf("  stage1_cycle_count stage1_instruction_count  stage2_cycle_count "
-         " stage2_instruction_count  stage3_cycle_count "
-         "stage3_instruction_count  ");
-#else
-  printf("(you are not under linux, so perf counters are disaabled)");
-#endif
-  printf("\n");
-  printf("%zu %zu %zu %zu %zu %zu %zu %zu %zu %zu %zu %zu ", s.integer_count,
-         s.float_count, s.string_count, s.backslash_count,
-         s.non_ascii_byte_count, s.object_count, s.array_count, s.null_count,
-         s.true_count, s.false_count, s.byte_count, s.structural_indexes_count);
-#ifdef __linux__
-  simdjson::dom::parser parser;
-  simdjson::error_code alloc_error = parser.allocate(p.size());
-  if (alloc_error) {
-    std::cerr << alloc_error << std::endl;
-    return EXIT_FAILURE;
-  }
-  const uint32_t iterations = p.size() < 1 * 1000 * 1000 ? 1000 : 50;
-  std::vector<int> evts;
-  evts.push_back(PERF_COUNT_HW_CPU_CYCLES);
-  evts.push_back(PERF_COUNT_HW_INSTRUCTIONS);
-  LinuxEvents<PERF_TYPE_HARDWARE> unified(evts);
-  unsigned long cy1 = 0, cy2 = 0;
-  unsigned long cl1 = 0, cl2 = 0;
-  std::vector<unsigned long long> results;
-  results.resize(evts.size());
-  for (uint32_t i = 0; i < iterations; i++) {
-    unified.start();
-    // The default template is simdjson::architecture::NATIVE.
-    bool isok = (parser.implementation->stage1((const uint8_t *)p.data(), p.size(), simdjson::stage1_mode::regular) == simdjson::SUCCESS);
-    unified.end(results);
-
-    cy1 += results[0];
-    cl1 += results[1];
-
-    unified.start();
-    isok = isok && (parser.implementation->stage2(parser.doc) == simdjson::SUCCESS);
-    unified.end(results);
-
-    cy2 += results[0];
-    cl2 += results[1];
-    if (!isok) {
-      std::cerr << "failure?" << std::endl;
-    }
-  }
-  printf("%f %f %f %f ", static_cast<double>(cy1) / static_cast<double>(iterations), static_cast<double>(cl1) / static_cast<double>(iterations),
-         static_cast<double>(cy2) / static_cast<double>(iterations), static_cast<double>(cl2) / static_cast<double>(iterations));
-#endif // __linux__
-  printf("\n");
-  return EXIT_SUCCESS;
-}

benchmark/event_counter.h

@@ -1,201 +0,0 @@
-#ifndef __EVENT_COUNTER_H
-#define __EVENT_COUNTER_H
-
-#ifndef SIMDJSON_SIMPLE_PERFORMANCE_COUNTERS
-#ifdef __aarch64__
-// on ARM, we use just cycles and instructions
-#define SIMDJSON_SIMPLE_PERFORMANCE_COUNTERS 1
-#else
-// elsewhere, we try to use four counters.
-#define SIMDJSON_SIMPLE_PERFORMANCE_COUNTERS 0
-#endif
-#endif
-#include <cassert>
-#include <cctype>
-#ifndef _MSC_VER
-#include <dirent.h>
-#endif
-#include <unistd.h>
-#include <cinttypes>
-
-#include <cstdio>
-#include <cstdlib>
-#include <cstring>
-
-#include <algorithm>
-#include <chrono>
-#include <cstring>
-#include <fstream>
-#include <iomanip>
-#include <iostream>
-#include <map>
-#include <set>
-#include <sstream>
-#include <string>
-#include <vector>
-
-#ifdef __linux__
-#include "linux-perf-events.h"
-#include <libgen.h>
-#endif
-
-#if __APPLE__ &&  __aarch64__
-#include "apple/apple_arm_events.h"
-#endif
-
-#include "simdjson.h"
-
-using std::string;
-using std::vector;
-using std::chrono::steady_clock;
-using std::chrono::time_point;
-using std::chrono::duration;
-
-struct event_count {
-  duration<double> elapsed;
-  vector<unsigned long long> event_counts;
-  event_count() : elapsed(0), event_counts{0,0,0,0,0} {}
-  event_count(const duration<double> _elapsed, const vector<unsigned long long> _event_counts) : elapsed(_elapsed), event_counts(_event_counts) {}
-  event_count(const event_count& other): elapsed(other.elapsed), event_counts(other.event_counts) { }
-
-  // The types of counters (so we can read the getter more easily)
-  #if SIMDJSON_SIMPLE_PERFORMANCE_COUNTERS
-  enum event_counter_types {
-    CPU_CYCLES,
-    INSTRUCTIONS
-  };
-  #else
-  enum event_counter_types {
-    CPU_CYCLES,
-    INSTRUCTIONS,
-    BRANCH_MISSES,
-    CACHE_REFERENCES,
-    CACHE_MISSES
-  };
-  #endif
-  double elapsed_sec() const { return duration<double>(elapsed).count(); }
-  double elapsed_ns() const { return duration<double, std::nano>(elapsed).count(); }
-  double cycles() const { return static_cast<double>(event_counts[CPU_CYCLES]); }
-  double instructions() const { return static_cast<double>(event_counts[INSTRUCTIONS]); }
-#if !SIMDJSON_SIMPLE_PERFORMANCE_COUNTERS
-  double branch_misses() const { return static_cast<double>(event_counts[BRANCH_MISSES]); }
-  double cache_references() const { return static_cast<double>(event_counts[CACHE_REFERENCES]); }
-  double cache_misses() const { return static_cast<double>(event_counts[CACHE_MISSES]); }
-#endif
-  event_count& operator=(const event_count& other) {
-    this->elapsed = other.elapsed;
-    this->event_counts = other.event_counts;
-    return *this;
-  }
-  event_count operator+(const event_count& other) const {
-    return event_count(elapsed+other.elapsed, {
-      event_counts[0]+other.event_counts[0],
-      event_counts[1]+other.event_counts[1],
-      event_counts[2]+other.event_counts[2],
-      event_counts[3]+other.event_counts[3],
-      event_counts[4]+other.event_counts[4],
-    });
-  }
-
-  void operator+=(const event_count& other) {
-    *this = *this + other;
-  }
-};
-
-struct event_aggregate {
-  int iterations = 0;
-  event_count total{};
-  event_count best{};
-  event_count worst{};
-
-  event_aggregate() {}
-
-  void operator<<(const event_count& other) {
-    if (iterations == 0 || other.elapsed < best.elapsed) {
-      best = other;
-    }
-    if (iterations == 0 || other.elapsed > worst.elapsed) {
-      worst = other;
-    }
-    iterations++;
-    total += other;
-  }
-
-  double elapsed_sec() const { return total.elapsed_sec() / iterations; }
-  double total_elapsed_ns() const { return total.elapsed_ns(); }
-  double elapsed_ns() const { return total.elapsed_ns() / iterations; }
-  double cycles() const { return total.cycles() / iterations; }
-  double instructions() const { return total.instructions() / iterations; }
-#if !SIMDJSON_SIMPLE_PERFORMANCE_COUNTERS
-  double branch_misses() const { return total.branch_misses() / iterations; }
-  double cache_references() const { return total.cache_references() / iterations; }
-  double cache_misses() const { return total.cache_misses() / iterations; }
-#endif
-};
-
-struct event_collector {
-  event_count count{};
-  time_point<steady_clock> start_clock{};
-
-#if defined(__linux__)
-  LinuxEvents<PERF_TYPE_HARDWARE> linux_events;
-  event_collector() : linux_events(vector<int>{
-  #if SIMDJSON_SIMPLE_PERFORMANCE_COUNTERS
-    PERF_COUNT_HW_CPU_CYCLES,
-    PERF_COUNT_HW_INSTRUCTIONS,
-  #else
-    PERF_COUNT_HW_CPU_CYCLES,
-    PERF_COUNT_HW_INSTRUCTIONS,
-    PERF_COUNT_HW_BRANCH_MISSES,
-    PERF_COUNT_HW_CACHE_REFERENCES,
-    PERF_COUNT_HW_CACHE_MISSES
-  #endif
-  }) {}
-  bool has_events() {
-    return linux_events.is_working();
-  }
-#elif __APPLE__ &&  __aarch64__
-  AppleEvents apple_events;
-  performance_counters diff;
-  event_collector() : diff(0) {
-    apple_events.setup_performance_counters();
-  }
-  bool has_events() {
-    return apple_events.setup_performance_counters();
-  }
-#else
-  event_collector() {}
-  bool has_events() {
-    return false;
-  }
-#endif
-
-  simdjson_inline void start() {
-#if defined(__linux)
-    linux_events.start();
-#elif __APPLE__ &&  __aarch64__
-    if(has_events()) { diff = apple_events.get_counters(); }
-#endif
-    start_clock = steady_clock::now();
-  }
-  simdjson_inline event_count& end() {
-    time_point<steady_clock> end_clock = steady_clock::now();
-#if defined(__linux)
-    linux_events.end(count.event_counts);
-#elif __APPLE__ &&  __aarch64__
-    if(has_events()) {
-      performance_counters end = apple_events.get_counters();
-      diff = end - diff;
-    }
-    count.event_counts[0] = diff.cycles;
-    count.event_counts[1] = diff.instructions;
-    count.event_counts[2] = diff.missed_branches;
-    count.event_counts[3] = 0;
-    count.event_counts[4] = 0;
-#endif
-    count.elapsed = end_clock - start_clock;
-    return count;
-  }
-};
-
-#endif

benchmark/from/benchmark_helpers.h

@@ -1,7 +1,8 @@
 #ifndef BENCHMARK_HELPERS_H
 #define BENCHMARK_HELPERS_H
 
-#include "event_counter.h"
+#include <counters/event_counter.h>
+using namespace counters;
 #include <atomic>
 
 event_collector collector;

benchmark/json_benchmark/run_json_benchmark.h

@@ -1,7 +1,8 @@
 #pragma once
 
 #include "simdjson.h"
-#include "event_counter.h"
+#include <counters/event_counter.h>
+using namespace counters;
 #include <iostream>
 
 namespace json_benchmark {
@@ -58,11 +59,7 @@ template<typename B, typename R> static void run_json_benchmark(benchmark::State
   if (collector.has_events()) {
     state.counters["instructions"] = events.instructions();
     state.counters["cycles"]       = events.cycles();
-#if !SIMDJSON_SIMPLE_PERFORMANCE_COUNTERS
     state.counters["branch_miss"]  = events.branch_misses();
-    state.counters["cache_miss"]   = events.cache_misses();
-    state.counters["cache_ref"]    = events.cache_references();
-#endif
     state.counters["instructions_per_byte"]  = events.instructions() / double(bench.bytes_per_iteration());
     state.counters["instructions_per_cycle"] = events.instructions() / events.cycles();
     state.counters["cycles_per_byte"]        = events.cycles()       / double(bench.bytes_per_iteration());
@@ -70,11 +67,7 @@ template<typename B, typename R> static void run_json_benchmark(benchmark::State
 
     state.counters["best_instructions"] = events.best.instructions();
     state.counters["best_cycles"]       = events.best.cycles();
-#if !SIMDJSON_SIMPLE_PERFORMANCE_COUNTERS
     state.counters["best_branch_miss"]  = events.best.branch_misses();
-    state.counters["best_cache_miss"]   = events.best.cache_misses();
-    state.counters["best_cache_ref"]    = events.best.cache_references();
-#endif
 
     state.counters["best_instructions_per_byte"]  = events.best.instructions() / double(bench.bytes_per_iteration());
     state.counters["best_instructions_per_cycle"] = events.best.instructions() / events.best.cycles();
@@ -95,11 +88,7 @@ template<typename B, typename R> static void run_json_benchmark(benchmark::State
   if (collector.has_events()) {
     label << " instructions=" << setw(12) << uint64_t(events.best.instructions())     << setw(0);
     label << " cycles="       << setw(12) << uint64_t(events.best.cycles())           << setw(0);
-#if !SIMDJSON_SIMPLE_PERFORMANCE_COUNTERS
     label << " branch_miss="  << setw(8)  << uint64_t(events.best.branch_misses())    << setw(0);
-    label << " cache_miss="   << setw(8)  << uint64_t(events.best.cache_misses())     << setw(0);
-    label << " cache_ref="    << setw(10) << uint64_t(events.best.cache_references()) << setw(0);
-#endif
   }
 
   label << " items=" << setw(10) << bench.items_per_iteration() << setw(0);

benchmark/large_amazon_cellphones/large_amazon_cellphones.h

@@ -1,6 +1,7 @@
 #pragma once
 
 #include "json_benchmark/string_runner.h"
+#include <fstream>
 #include <map>
 #include <string>
 

benchmark/large_random/simdjson_ondemand_ranges.h

@@ -0,0 +1,32 @@
+#pragma once
+
+#if SIMDJSON_EXCEPTIONS && SIMDJSON_SUPPORTS_RANGES
+
+#include "large_random.h"
+
+namespace large_random {
+
+using namespace simdjson;
+
+// Identical to simdjson_ondemand but uses get_range() for iteration.
+// Demonstrates that the ranges wrapper has zero per-element overhead.
+struct simdjson_ondemand_ranges {
+  static constexpr diff_flags DiffFlags = diff_flags::NONE;
+
+  ondemand::parser parser{};
+
+  bool run(simdjson::padded_string &json, std::vector<point> &result) {
+    auto doc = parser.iterate(json);
+    for (auto coord_result : ondemand::get_range(doc.get_array())) {
+      ondemand::object coord = coord_result;
+      result.emplace_back(json_benchmark::point{coord.find_field("x"), coord.find_field("y"), coord.find_field("z")});
+    }
+    return true;
+  }
+};
+
+BENCHMARK_TEMPLATE(large_random, simdjson_ondemand_ranges)->UseManualTime();
+
+} // namespace large_random
+
+#endif // SIMDJSON_EXCEPTIONS && SIMDJSON_SUPPORTS_RANGES

benchmark/largerandom/sax.h

@@ -103,7 +103,12 @@ error_code Sax::RunNoExcept(const padded_string &json) noexcept {
 
 error_code Sax::Allocate(size_t new_capacity) {
   // string_capacity copied from document::allocate
-  size_t string_capacity = SIMDJSON_ROUNDUP_N(5 * new_capacity / 3 + SIMDJSON_PADDING, 64);
+  // a document with only zero-length strings... could have capacity/3 string
+  // and we would need capacity/3 * 5 bytes on the string buffer
+  if(5 * (new_capacity / 3) + SIMDJSON_PADDING < SIMDJSON_PADDING) {
+    return CAPACITY; // overflow, only happen on legacy 32-bit systems with very large capacity
+  }
+  size_t string_capacity = SIMDJSON_ROUNDUP_N(5 * (new_capacity / 3) + SIMDJSON_PADDING, 64);
   string_buf.reset(new (std::nothrow) uint8_t[string_capacity]);
   if (auto error = dom_parser.set_capacity(new_capacity)) { return error; }
   if (capacity == 0) { // set max depth the first time only

benchmark/linux/linux-perf-events.h

@@ -1,105 +0,0 @@
-#pragma once
-#ifdef __linux__
-
-#include <asm/unistd.h>       // for __NR_perf_event_open
-#include <linux/perf_event.h> // for perf event constants
-#include <sys/ioctl.h>        // for ioctl
-#include <unistd.h>           // for syscall
-
-#include <cerrno>  // for errno
-#include <cstring> // for memset
-#include <stdexcept>
-
-#include <iostream>
-#include <vector>
-
-template <int TYPE = PERF_TYPE_HARDWARE> class LinuxEvents {
-  int fd;
-  bool working;
-  perf_event_attr attribs{};
-  size_t num_events{};
-  std::vector<uint64_t> temp_result_vec{};
-  std::vector<uint64_t> ids{};
-
-public:
-  explicit LinuxEvents(std::vector<int> config_vec) : fd(0), working(true) {
-    memset(&attribs, 0, sizeof(attribs));
-    attribs.type = TYPE;
-    attribs.size = sizeof(attribs);
-    attribs.disabled = 1;
-    attribs.exclude_kernel = 1;
-    attribs.exclude_hv = 1;
-
-    attribs.sample_period = 0;
-    attribs.read_format = PERF_FORMAT_GROUP | PERF_FORMAT_ID;
-    const int pid = 0;  // the current process
-    const int cpu = -1; // all CPUs
-    const unsigned long flags = 0;
-
-    int group = -1; // no group
-    num_events = config_vec.size();
-    ids.resize(config_vec.size());
-    uint32_t i = 0;
-    for (auto config : config_vec) {
-      attribs.config = config;
-      int _fd = static_cast<int>(syscall(__NR_perf_event_open, &attribs, pid, cpu, group, flags));
-      if (_fd == -1) {
-        report_error("perf_event_open");
-      }
-      ioctl(_fd, PERF_EVENT_IOC_ID, &ids[i++]);
-      if (group == -1) {
-        group = _fd;
-        fd = _fd;
-      }
-    }
-
-    temp_result_vec.resize(num_events * 2 + 1);
-  }
-
-  ~LinuxEvents() { if (fd != -1) { close(fd); } }
-
-  inline void start() {
-    if (fd != -1) {
-      if (ioctl(fd, PERF_EVENT_IOC_RESET, PERF_IOC_FLAG_GROUP) == -1) {
-        report_error("ioctl(PERF_EVENT_IOC_RESET)");
-      }
-
-      if (ioctl(fd, PERF_EVENT_IOC_ENABLE, PERF_IOC_FLAG_GROUP) == -1) {
-        report_error("ioctl(PERF_EVENT_IOC_ENABLE)");
-      }
-    }
-  }
-
-  inline void end(std::vector<unsigned long long> &results) {
-    if (fd != -1) {
-      if (ioctl(fd, PERF_EVENT_IOC_DISABLE, PERF_IOC_FLAG_GROUP) == -1) {
-        report_error("ioctl(PERF_EVENT_IOC_DISABLE)");
-      }
-
-      if (read(fd, temp_result_vec.data(), temp_result_vec.size() * 8) == -1) {
-        report_error("read");
-      }
-    }
-    // our actual results are in slots 1,3,5, ... of this structure
-    for (uint32_t i = 1; i < temp_result_vec.size(); i += 2) {
-      results[i / 2] = temp_result_vec[i];
-    }
-    for (uint32_t i = 2; i < temp_result_vec.size(); i += 2) {
-      if(ids[i/2-1] != temp_result_vec[i]) {
-        report_error("event mismatch");
-      }
-    }
-
-
-  }
-
-  bool is_working() {
-    return working;
-  }
-
-private:
-  void report_error(const std::string &) {
-    working = false;
-  }
-};
-#endif

benchmark/partial_tweets/tweet.h

@@ -10,7 +10,7 @@ namespace partial_tweets {
 //     {
 //       "created_at": "Sun Aug 31 00:29:15 +0000 2014",
 //       "id": 505874924095815700,
-//       "text": "@aym0566x \n\n名前:前田あゆみ\n第一印象:なんか怖っ！\n今の印象:とりあえずキモい。噛み合わない\n好きなところ:ぶすでキモいとこ😋✨✨\n思い出:んーーー、ありすぎ😊❤️\nLINE交換できる？:あぁ……ごめん✋\nトプ画をみて:照れますがな😘✨\n一言:お前は一生もんのダチ💖",
+//       "text": "@aym0566x ...",
 //       "in_reply_to_status_id": null,
 //       "user": {
 //         "id": 1186275104,

benchmark/static_reflect/benchmark_utils/benchmark_helper.h

@@ -1,6 +1,7 @@
 #ifndef BENCHMARK_HELPER_HPP
 #define BENCHMARK_HELPER_HPP
-#include "event_counter.h"
+#include <counters/event_counter.h>
+using namespace counters;
 #include <atomic>
 
 inline event_collector &get_collector() {

benchmark/static_reflect/citm_catalog_benchmark/benchmark_parsing_citm.cpp

@@ -79,15 +79,13 @@ template <class T> void bench_simdjson_from_parsing(const std::string &json_str)
   volatile bool result = true;
   pretty_print(1, input_volume, "bench_simdjson_from_parsing",
                bench([&padded, &result]() {
-                 try {
-                   // Using simdjson::from API directly with padded string
-                   // This will throw an exception if parsing fails
-                   T my_struct = simdjson::from(padded);
-                   result = true;
-                 } catch (const std::exception& e) {
-                   result = false;
-                   printf("parse error: %s\n", e.what());
-                 }
+                 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

benchmark/static_reflect/citm_catalog_benchmark/benchmark_serialization_citm_catalog.cpp

@@ -39,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
 
@@ -152,7 +147,10 @@ void bench_simdjson_static_reflection_reuse(CitmCatalog &data) {
 void bench_simdjson_to(CitmCatalog &data) {
   // First run to determine size
   std::string output_init;
-  simdjson::builder::to_json(data, 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);
 
@@ -161,7 +159,10 @@ void bench_simdjson_to(CitmCatalog &data) {
                bench([&data, &measured_volume, &output_volume]() {
                  // Fresh allocation each iteration - fair comparison
                  std::string output;
-                 simdjson::builder::to_json(data, 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");
@@ -172,7 +173,10 @@ void bench_simdjson_to(CitmCatalog &data) {
 // Optimized variant: reuses pre-allocated string
 void bench_simdjson_to_reuse(CitmCatalog &data) {
   std::string output;
-  simdjson::builder::to_json(data, 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);
 
@@ -183,7 +187,10 @@ void bench_simdjson_to_reuse(CitmCatalog &data) {
   pretty_print(sizeof(data), output_volume, "bench_simdjson_to_reuse",
                bench([&data, &measured_volume, &output_volume, &output]() {
                  // Reuse the pre-allocated string - avoids allocation
-                 simdjson::builder::to_json(data, 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");
@@ -192,20 +199,20 @@ void bench_simdjson_to_reuse(CitmCatalog &data) {
 }
 #endif
 
-std::string read_file(const std::string &file_path, size_t read_size = 65536) {
+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 matches any of the comma-separated filters
@@ -243,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;
   }
@@ -289,7 +296,7 @@ int main(int argc, char* argv[]) {
   if (matches_filter("rust", filter)) {
     // 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/rapidjson_citm_catalog_data.h

@@ -27,14 +27,14 @@ CitmCatalog rapidjson_deserialize_citm(const std::string& json_str) {
             Event event;
             const Value& ev = it->value;
 
-            if (ev.HasMember("id") && ev["id"].IsUint64())
-                event.id = ev["id"].GetUint64();
-            if (ev.HasMember("name") && ev["name"].IsString())
-                event.name = ev["name"].GetString();
             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())
@@ -77,60 +77,23 @@ CitmCatalog rapidjson_deserialize_citm(const std::string& json_str) {
                 perf.venueCode = p["venueCode"].GetString();
             if (p.HasMember("name") && p["name"].IsString())
                 perf.name = p["name"].GetString();
-            if (p.HasMember("logo") && p["logo"].IsString())
-                perf.logo = p["logo"].GetString();
-            if (p.HasMember("seatMapImage") && p["seatMapImage"].IsString())
-                perf.seatMapImage = p["seatMapImage"].GetString();
-
-            // Parse prices
-            if (p.HasMember("prices") && p["prices"].IsArray()) {
-                const Value& prices = p["prices"];
-                for (SizeType j = 0; j < prices.Size(); j++) {
-                    CITMPrice price;
-                    const Value& pr = prices[j];
-                    if (pr.HasMember("amount") && pr["amount"].IsUint64())
-                        price.amount = pr["amount"].GetUint64();
-                    if (pr.HasMember("audienceSubCategoryId") && pr["audienceSubCategoryId"].IsUint64())
-                        price.audienceSubCategoryId = pr["audienceSubCategoryId"].GetUint64();
-                    if (pr.HasMember("seatCategoryId") && pr["seatCategoryId"].IsUint64())
-                        price.seatCategoryId = pr["seatCategoryId"].GetUint64();
-                    perf.prices.push_back(price);
-                }
-            }
-
-            // Parse seatCategories
-            if (p.HasMember("seatCategories") && p["seatCategories"].IsArray()) {
-                const Value& seatCats = p["seatCategories"];
-                for (SizeType j = 0; j < seatCats.Size(); j++) {
-                    CITMSeatCategory seatCat;
-                    const Value& sc = seatCats[j];
-                    if (sc.HasMember("seatCategoryId") && sc["seatCategoryId"].IsUint64())
-                        seatCat.seatCategoryId = sc["seatCategoryId"].GetUint64();
-                    if (sc.HasMember("areas") && sc["areas"].IsArray()) {
-                        const Value& areas = sc["areas"];
-                        for (SizeType k = 0; k < areas.Size(); k++) {
-                            CITMArea area;
-                            const Value& ar = areas[k];
-                            if (ar.HasMember("areaId") && ar["areaId"].IsUint64())
-                                area.areaId = ar["areaId"].GetUint64();
-                            if (ar.HasMember("blockIds") && ar["blockIds"].IsArray()) {
-                                const Value& blocks = ar["blockIds"];
-                                for (SizeType l = 0; l < blocks.Size(); l++) {
-                                    if (blocks[l].IsUint64())
-                                        area.blockIds.push_back(blocks[l].GetUint64());
-                                }
-                            }
-                            seatCat.areas.push_back(area);
-                        }
-                    }
-                    perf.seatCategories.push_back(seatCat);
-                }
-            }
 
             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;
 }
 
@@ -145,24 +108,24 @@ std::string rapidjson_serialize_citm(const CitmCatalog& catalog) {
     for (const auto& [key, event] : catalog.events) {
         Value event_obj(kObjectType);
 
-        event_obj.AddMember("id", event.id, allocator);
-
-        Value name;
-        name.SetString(event.name.c_str(), allocator);
-        event_obj.AddMember("name", name, allocator);
-
         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);
@@ -211,53 +174,6 @@ std::string rapidjson_serialize_citm(const CitmCatalog& catalog) {
             perf_obj.AddMember("name", name, allocator);
         }
 
-        if (perf.logo) {
-            Value logo;
-            logo.SetString(perf.logo->c_str(), allocator);
-            perf_obj.AddMember("logo", logo, allocator);
-        }
-
-        if (perf.seatMapImage) {
-            Value seatMap;
-            seatMap.SetString(perf.seatMapImage->c_str(), allocator);
-            perf_obj.AddMember("seatMapImage", seatMap, allocator);
-        }
-
-        // Serialize prices
-        Value prices_array(kArrayType);
-        for (const auto& price : perf.prices) {
-            Value price_obj(kObjectType);
-            price_obj.AddMember("amount", price.amount, allocator);
-            price_obj.AddMember("audienceSubCategoryId", price.audienceSubCategoryId, allocator);
-            price_obj.AddMember("seatCategoryId", price.seatCategoryId, allocator);
-            prices_array.PushBack(price_obj, allocator);
-        }
-        perf_obj.AddMember("prices", prices_array, allocator);
-
-        // Serialize seatCategories
-        Value seatCats_array(kArrayType);
-        for (const auto& seatCat : perf.seatCategories) {
-            Value seatCat_obj(kObjectType);
-            seatCat_obj.AddMember("seatCategoryId", seatCat.seatCategoryId, allocator);
-
-            Value areas_array(kArrayType);
-            for (const auto& area : seatCat.areas) {
-                Value area_obj(kObjectType);
-                area_obj.AddMember("areaId", area.areaId, allocator);
-
-                Value blockIds_array(kArrayType);
-                for (uint64_t blockId : area.blockIds) {
-                    blockIds_array.PushBack(blockId, allocator);
-                }
-                area_obj.AddMember("blockIds", blockIds_array, allocator);
-
-                areas_array.PushBack(area_obj, allocator);
-            }
-            seatCat_obj.AddMember("areas", areas_array, allocator);
-
-            seatCats_array.PushBack(seatCat_obj, allocator);
-        }
-        perf_obj.AddMember("seatCategories", seatCats_array, allocator);
 
         performances_array.PushBack(perf_obj, allocator);
     }
@@ -270,4 +186,4 @@ std::string rapidjson_serialize_citm(const CitmCatalog& catalog) {
     return buffer.GetString();
 }
 
-#endif // RAPIDJSON_CITM_CATALOG_DATA_H
+#endif // RAPIDJSON_CITM_CATALOG_DATA_H

benchmark/static_reflect/serde-benchmark/lib.rs

@@ -38,6 +38,7 @@ pub struct Status {
 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 {
@@ -49,10 +50,17 @@ pub unsafe extern "C" fn twitter_from_str(raw_input: *const c_char, raw_input_le
 }
 
 #[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]
@@ -152,6 +160,8 @@ pub struct CitmCatalog {
     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]
@@ -197,29 +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;
+}
 
-    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.
@@ -279,7 +277,7 @@ pub unsafe extern "C" fn measure_twitter_ffi_overhead(
     use std::time::Instant;
 
     let twitter_data = &*raw;
-    let mut output_size: u64 = 0;
+    let output_size: u64;
 
     // Warm-up run
     let warmup = serde_json::to_string(&twitter_data).unwrap();
@@ -321,7 +319,7 @@ pub unsafe extern "C" fn measure_citm_ffi_overhead(
     use std::time::Instant;
 
     let catalog = &*raw;
-    let mut output_size: u64 = 0;
+    let output_size: u64;
 
     // Warm-up run
     let warmup = serde_json::to_string(&catalog).unwrap();

benchmark/static_reflect/serde-benchmark/serde_benchmark.h

@@ -34,7 +34,9 @@ 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);
 
@@ -43,8 +45,9 @@ 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);

benchmark/static_reflect/twitter_benchmark/benchmark_parsing_twitter.cpp

@@ -82,36 +82,33 @@ void bench_simdjson_from_parsing(const std::string &json_str) {
   volatile bool result = true;
   pretty_print(1, input_volume, "bench_simdjson_from_parsing",
                bench([&padded, &result]() {
-                 try {
-                   // Using simdjson::from API directly with padded string
-                   // This will throw an exception if parsing fails
-                   T my_struct = simdjson::from(padded);
-                   result = true;
-                 } catch (const std::exception& e) {
-                   result = false;
-                   printf("parse error: %s\n", e.what());
-                 }
+                 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 parsing disabled - deserialization functions not implemented
-// 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");
-//                  }
-//                }));
-// }
+ 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) {
@@ -204,10 +201,9 @@ int main(int argc, char* argv[]) {
   std::string json_str = read_file(JSON_FILE);
 
   // Benchmarking the parsing
-  // Nlohmann parsing disabled - deserialization functions not implemented
-  // if (matches_filter("nlohmann", filter)) {
-  //   bench_nlohmann_parsing(json_str);
-  // }
+  if (matches_filter("nlohmann", filter)) {
+    bench_nlohmann_parsing(json_str);
+  }
 #ifdef SIMDJSON_COMPETITION_RAPIDJSON
   if (matches_filter("rapidjson", filter)) {
     bench_rapidjson_parsing(json_str);

benchmark/static_reflect/twitter_benchmark/benchmark_serialization_twitter.cpp

@@ -39,72 +39,16 @@ 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();
                }));
 }
-
-// Measures and reports FFI overhead for Rust/serde serialization
-void measure_rust_ffi_overhead(serde_benchmark::TwitterData *data) {
-  printf("\n=== Rust/serde FFI Overhead Analysis ===\n");
-
-  // First, measure the per-call FFI benchmark (what we normally report)
-  const uint64_t iterations = 10000;
-
-  // Time the per-call FFI approach (N separate FFI calls)
-  auto start_ffi = std::chrono::steady_clock::now();
-  for (uint64_t i = 0; i < iterations; i++) {
-    const char * output = serde_benchmark::str_from_twitter(data);
-    serde_benchmark::free_string(output);
-  }
-  auto end_ffi = std::chrono::steady_clock::now();
-  uint64_t ffi_total_ns = std::chrono::duration_cast<std::chrono::nanoseconds>(end_ffi - start_ffi).count();
-
-  // Now measure via the Rust-internal timing (1 FFI call, N serializations inside Rust)
-  serde_benchmark::FfiOverheadResult result = serde_benchmark::measure_twitter_ffi_overhead(data, iterations);
-
-  // Calculate overhead
-  double per_call_ffi_ns = static_cast<double>(ffi_total_ns) / iterations;
-  double per_call_pure_serde_ns = static_cast<double>(result.pure_serde_ns) / iterations;
-  double per_call_serde_cstring_ns = static_cast<double>(result.serde_plus_cstring_ns) / iterations;
-
-  double cstring_overhead_ns = per_call_serde_cstring_ns - per_call_pure_serde_ns;
-  double ffi_call_overhead_ns = per_call_ffi_ns - per_call_serde_cstring_ns;
-  double total_overhead_ns = per_call_ffi_ns - per_call_pure_serde_ns;
-
-  double overhead_percent = (total_overhead_ns / per_call_ffi_ns) * 100.0;
-  double cstring_percent = (cstring_overhead_ns / per_call_ffi_ns) * 100.0;
-  double ffi_call_percent = (ffi_call_overhead_ns / per_call_ffi_ns) * 100.0;
-
-  // Calculate throughput in MB/s
-  double output_mb = static_cast<double>(result.output_size) / (1024.0 * 1024.0);
-  double pure_serde_throughput = (output_mb * 1e9) / per_call_pure_serde_ns;
-  double with_ffi_throughput = (output_mb * 1e9) / per_call_ffi_ns;
-
-  printf("# Iterations: %lu\n", iterations);
-  printf("# Output size: %lu bytes\n", result.output_size);
-  printf("#\n");
-  printf("# Timing breakdown (per iteration):\n");
-  printf("#   Pure serde_json::to_string():     %8.1f ns  (%.1f MB/s)\n", per_call_pure_serde_ns, pure_serde_throughput);
-  printf("#   + CString conversion:             %8.1f ns  (+%.1f%% overhead)\n", per_call_serde_cstring_ns, cstring_percent);
-  printf("#   + FFI call/return overhead:       %8.1f ns  (+%.1f%% overhead)\n", per_call_ffi_ns, ffi_call_percent);
-  printf("#\n");
-  printf("# Total FFI overhead: %.1f ns (%.2f%% of total time)\n", total_overhead_ns, overhead_percent);
-  printf("#   - CString conversion: %.1f ns (%.2f%%)\n", cstring_overhead_ns, cstring_percent);
-  printf("#   - FFI call mechanics: %.1f ns (%.2f%%)\n", ffi_call_overhead_ns, ffi_call_percent);
-  printf("#\n");
-  printf("# Throughput comparison:\n");
-  printf("#   Pure Rust (no FFI):    %.1f MB/s\n", pure_serde_throughput);
-  printf("#   With FFI overhead:     %.1f MB/s  (reported in benchmarks)\n", with_ffi_throughput);
-  printf("#   Performance penalty:   %.2f%%\n", overhead_percent);
-  printf("===========================================\n\n");
-}
 #endif
 
 // Fair allocation variant: allocates fresh buffer each iteration (matches other libraries)
@@ -169,7 +113,10 @@ template <class T> void bench_simdjson_static_reflection_reuse(T &data) {
 template <class T> void bench_simdjson_to(T &data) {
   // First run to determine size
   std::string output_init;
-  simdjson::builder::to_json(data, 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);
 
@@ -178,7 +125,10 @@ template <class T> void bench_simdjson_to(T &data) {
                bench([&data, &measured_volume, &output_volume]() {
                  // Fresh allocation each iteration - fair comparison
                  std::string output;
-                 simdjson::builder::to_json(data, 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");
@@ -189,7 +139,10 @@ template <class T> void bench_simdjson_to(T &data) {
 // Optimized variant: reuses pre-allocated string
 template <class T> void bench_simdjson_to_reuse(T &data) {
   std::string output;
-  simdjson::builder::to_json(data, 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);
 
@@ -200,7 +153,10 @@ template <class T> void bench_simdjson_to_reuse(T &data) {
   pretty_print(sizeof(data), output_volume, "bench_simdjson_to_reuse",
                bench([&data, &measured_volume, &output_volume, &output]() {
                  // Reuse the pre-allocated string - avoids allocation
-                 simdjson::builder::to_json(data, 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");
@@ -248,18 +204,18 @@ size_t WriteCallback(void *contents, size_t size, size_t nmemb, void *userp) {
   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 matches any of the comma-separated filters
@@ -297,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;
   }
@@ -341,13 +297,11 @@ int main(int argc, char* argv[]) {
 #endif
 #ifdef SIMDJSON_RUST_VERSION
   if (matches_filter("rust", filter)) {
-    serde_benchmark::TwitterData * td = serde_benchmark::twitter_from_str(json_str.c_str(), json_str.size());
+    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);
-      // Always run FFI overhead analysis when rust benchmark runs
-      measure_rust_ffi_overhead(td);
       serde_benchmark::free_twitter(td);
     }
   }

benchmark_fairness.md

@@ -1,308 +0,0 @@
-# JSON Serialization Benchmark Fairness Analysis
-
-This document provides a rigorous analysis of the serialization benchmarks comparing simdjson's C++26 reflection-based serialization against competing libraries. This analysis is intended to support academic publication and ensures methodological transparency.
-
-## Executive Summary
-
-After comprehensive review and fixes, the benchmarks are **fair and suitable for academic publication** with the following caveats:
-- All libraries serialize identical data structures with matching output sizes (Twitter dataset)
-- CITM dataset has one known discrepancy (reflect-cpp) which is documented
-- Rust/serde benchmarks include inherent FFI overhead, documented below
-- Memory allocation strategies are now equalized with both "fair" and "optimized" variants provided
-
----
-
-## 1. Benchmark Methodology
-
-### 1.1 Timing Infrastructure
-
-The benchmark uses `event_counter.h` which provides:
-
-```cpp
-// benchmark_helper.h - Core timing loop
-for (size_t i = 0; i < N; i++) {
-    std::atomic_thread_fence(std::memory_order_acquire);
-    collector.start();
-    function();
-    std::atomic_thread_fence(std::memory_order_release);
-    event_count allocate_count = collector.end();
-    aggregate << allocate_count;
-    // Continue until min_time_ns (1 second) elapsed
-}
-```
-
-**Key characteristics:**
-- **High-precision timing**: `std::chrono::steady_clock` for wall-clock time
-- **Hardware counters**: Linux perf events and Apple Silicon performance counters when available
-- **Warm-up period**: Minimum 10 iterations before measurement
-- **Convergence**: Continues until 1 second total elapsed or 100,000 iterations
-- **Memory barriers**: `std::atomic_thread_fence` prevents instruction reordering
-- **Result aggregation**: Reports average of all iterations
-
-**Assessment**: ✅ **FAIR** - Follows established benchmarking best practices.
-
-### 1.2 Compilation Settings
-
-All libraries are compiled with equivalent optimization settings:
-
-| Component | Compiler | Flags |
-|-----------|----------|-------|
-| C++ code | clang-p2996 (Clang 21.0.0) | `-O2 -std=c++26 -freflection` |
-| Rust code | rustc 1.63.0 | `--release` (equivalent to `-O3`) |
-
-**Assessment**: ✅ **FAIR** - All code optimized equivalently.
-
----
-
-## 2. Data Structure Equivalence
-
-### 2.1 Twitter Dataset
-
-All libraries serialize the same simplified Twitter schema:
-
-```cpp
-struct User {
-    uint64_t id;
-    std::string name, screen_name, location, description;
-    bool verified;
-    uint64_t followers_count, friends_count, statuses_count;
-};
-
-struct Status {
-    std::string created_at;
-    uint64_t id;
-    std::string text;
-    User user;
-    uint64_t retweet_count, favorite_count;
-};
-
-struct TwitterData {
-    std::vector<Status> statuses;
-};
-```
-
-**Output Volume Verification (Post-Fix):**
-
-| Library | Output Size | Match |
-|---------|-------------|-------|
-| simdjson (static reflection) | 81,927 bytes | ✅ |
-| simdjson (to_json) | 81,927 bytes | ✅ |
-| nlohmann::json | 81,927 bytes | ✅ |
-| yyjson | 81,927 bytes | ✅ |
-| Rust/serde | 81,927 bytes | ✅ |
-| reflect-cpp | 81,927 bytes | ✅ |
-
-**Assessment**: ✅ **FAIR** - All libraries produce identical output sizes.
-
-**Note**: The benchmark uses a simplified schema (9 User fields, 6 Status fields) compared to the original twitter.json (30+ User fields, 20+ Status fields). This is documented and consistent across all libraries.
-
-### 2.2 CITM Catalog Dataset
-
-The CITM benchmark serializes a subset of the full citm_catalog.json:
-
-```cpp
-struct CitmCatalog {
-    std::map<std::string, CITMEvent> events;      // 184 events
-    std::vector<CITMPerformance> performances;    // 243 performances
-};
-```
-
-**Output Volume Verification:**
-
-| Library | Output Size | Match | Notes |
-|---------|-------------|-------|-------|
-| simdjson (static reflection) | 496,682 bytes | ✅ | Reference |
-| simdjson (to_json) | 496,682 bytes | ✅ | |
-| nlohmann::json | 496,682 bytes | ✅ | |
-| Rust/serde | 496,682 bytes | ✅ | **Fixed** (was 502,729) |
-| reflect-cpp | 476,270 bytes | ⚠️ | 20,412 bytes less |
-
-**reflect-cpp Discrepancy Analysis:**
-
-The 20,412-byte difference is due to reflect-cpp's handling of `std::optional` fields:
-- simdjson/nlohmann output `"field":null` for empty optionals
-- reflect-cpp omits empty optional fields entirely
-
-This is a semantic design choice, not an error. Both representations are valid JSON. For benchmarking purposes:
-- reflect-cpp has slightly less work (smaller output)
-- This gives reflect-cpp a ~4% advantage in bytes written
-- The performance comparison remains meaningful as a real-world scenario
-
-**Assessment**: ⚠️ **DOCUMENTED DISCREPANCY** - reflect-cpp produces valid but smaller JSON. This should be noted in any publication.
-
----
-
-## 3. Memory Allocation Fairness
-
-### 3.1 Issue Identified
-
-The original benchmark had an unfair advantage for simdjson:
-- simdjson reused pre-allocated buffers across iterations
-- Competitors allocated fresh memory each iteration
-
-Memory allocation can account for 10-30% of serialization time, making this a significant bias.
-
-### 3.2 Fix Applied
-
-We now provide **two variants** for each simdjson benchmark:
-
-1. **Fair variant** (`bench_simdjson_static_reflection`, `bench_simdjson_to`):
-   - Allocates fresh buffer each iteration
-   - Matches behavior of nlohmann, yyjson, Rust, reflect-cpp
-   - **Use this for cross-library comparison**
-
-2. **Optimized variant** (`bench_simdjson_reuse_buffer`, `bench_simdjson_to_reuse`):
-   - Reuses pre-allocated buffer across iterations
-   - Demonstrates API's potential when buffer reuse is possible
-   - **Use this to show API design benefits**
-
-### 3.3 Code Changes
-
-**Before (unfair):**
-```cpp
-template <class T> void bench_simdjson_static_reflection(T &data) {
-    simdjson::builder::string_builder sb;  // Reused across iterations
-    // ...
-    bench([&sb, ...]() {
-        sb.clear();  // Just clears, doesn't deallocate
-        simdjson::builder::append(sb, data);
-    });
-}
-```
-
-**After (fair):**
-```cpp
-template <class T> void bench_simdjson_static_reflection(T &data) {
-    // ...
-    bench([...]() {
-        simdjson::builder::string_builder sb;  // Fresh each iteration
-        simdjson::builder::append(sb, data);
-    });
-}
-```
-
-**Assessment**: ✅ **FIXED** - Both fair and optimized variants now available.
-
----
-
-## 4. Rust/serde FFI Overhead
-
-### 4.1 Issue
-
-The Rust benchmark crosses the C/Rust FFI boundary, adding overhead not present in pure Rust usage:
-
-```rust
-// lib.rs - FFI function
-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();  // Serialize
-    CString::new(serialized.as_str()).unwrap().into_raw()  // Convert to C string
-}
-```
-
-The FFI overhead includes:
-1. FFI function call overhead (~10-20ns)
-2. `CString` allocation and copy from Rust `String`
-3. Return value marshaling
-
-### 4.2 Estimated Impact
-
-Based on typical FFI overhead measurements:
-- Per-call overhead: ~50-100ns
-- For 81KB output: overhead is <0.1% of total time
-- **Impact on benchmark**: Negligible (<1% for this data size)
-
-### 4.3 Recommendation
-
-For academic publication, note:
-> "Rust/serde numbers include FFI marshaling overhead. Pure Rust applications would see modestly better performance."
-
-**Assessment**: ⚠️ **DOCUMENTED** - Small but present overhead, negligible for this benchmark.
-
----
-
-## 5. Final Benchmark Results
-
-### 5.1 Twitter Serialization
-
-| Library | Throughput (MB/s) | Relative to simdjson | Notes |
-|---------|-------------------|----------------------|-------|
-| **simdjson (buffer reuse)** | **4,483** | 1.00x | Optimized: reuses buffer |
-| simdjson (fresh alloc) | 4,005 | 0.89x | Fair: fresh allocation each iteration |
-| simdjson to_json (buffer reuse) | 3,698 | 0.82x | Optimized |
-| simdjson to_json (fresh alloc) | 3,687 | 0.82x | Fair |
-| yyjson | 1,923 | 0.43x | |
-| Rust/serde | 1,820 | 0.41x | Includes FFI overhead |
-| reflect-cpp | 1,502 | 0.34x | |
-| nlohmann::json | 208 | 0.05x | |
-
-**Key insight**: Buffer reuse provides ~12% improvement for the string_builder API. simdjson was designed with buffer reuse in mind, so this represents realistic production performance.
-
-### 5.2 CITM Catalog Serialization
-
-| Library | Throughput (MB/s) | Relative to simdjson | Notes |
-|---------|-------------------|----------------------|-------|
-| **simdjson (buffer reuse)** | **3,170** | 1.00x | Optimized: reuses buffer |
-| simdjson (fresh alloc) | 2,796 | 0.88x | Fair: fresh allocation each iteration |
-| simdjson to_json (fresh alloc) | 2,908 | 0.92x | Fair |
-| simdjson to_json (buffer reuse) | 2,803 | 0.88x | Optimized |
-| Rust/serde | 1,513 | 0.48x | Includes FFI overhead |
-| yyjson | 1,510 | 0.48x | |
-| reflect-cpp | 1,216 | 0.38x | Smaller output (476KB) |
-| nlohmann::json | 105 | 0.03x | |
-
-**Key insight**: Buffer reuse provides ~13% improvement for CITM. The `to_json` API shows minimal difference because the string growth pattern differs.
-
-**Note**: reflect-cpp output is 476,270 bytes vs 496,682 bytes for others due to omitting null optional fields (see Section 2.2).
-
----
-
-## 6. Summary of Fixes Made
-
-| Issue | Fix | File(s) Modified |
-|-------|-----|------------------|
-| Rust CITM struct mismatch | Rewrote to match C++ exactly | `serde-benchmark/lib.rs` |
-| Memory allocation unfairness | Added fair (fresh alloc) variants | `benchmark_serialization_twitter.cpp`, `benchmark_serialization_citm_catalog.cpp` |
-| CMake typo preventing Rust | Fixed `SIMDJSON_USER_RUST` → `SIMDJSON_USE_RUST` | `CMakeLists.txt`, `unified_benchmark.sh` |
-| Missing yyjson in serialization | Added yyjson benchmark | `benchmark_serialization_twitter.cpp` |
-
----
-
-## 7. Recommendations for Publication
-
-### 7.1 Claims Supported by Data
-
-✅ "simdjson with C++26 reflection achieves 4.0 GB/s serialization throughput"
-✅ "simdjson is 19x faster than nlohmann::json for serialization"
-✅ "simdjson is 2.2x faster than Rust/serde for serialization"
-✅ "simdjson is 2.1x faster than yyjson for serialization"
-✅ "simdjson is 2.7x faster than reflect-cpp for serialization"
-
-### 7.2 Caveats to Include
-
-1. **Simplified schema**: Benchmarks use simplified Twitter/CITM structures, not full schemas
-2. **reflect-cpp output size**: reflect-cpp produces ~4% smaller output for CITM due to optional field handling
-3. **Rust FFI overhead**: Rust numbers include small FFI overhead
-4. **Buffer reuse**: Higher numbers possible when buffer reuse is feasible (documented separately)
-
-### 7.3 Reproducibility
-
-To reproduce these results:
-
-```bash
-# Using Docker with Bloomberg clang-p2996
-./p2996/run_docker.sh "./unified_benchmark.sh --serialization --clean"
-```
-
----
-
-## 8. Conclusion
-
-After thorough analysis and fixes:
-
-1. **The benchmark is fair** for cross-library comparison when using the "fair" (fresh allocation) variants
-2. **All major discrepancies have been fixed** (Rust struct, memory allocation)
-3. **One known discrepancy remains documented** (reflect-cpp optional handling)
-4. **Results are reproducible** via the provided Docker environment
-
-The benchmark methodology follows established best practices and the results are suitable for academic publication with the documented caveats.

benchmark_writeup.md

@@ -1,748 +0,0 @@
-# JSON Serialization Benchmark: Research-Grade Analysis
-
-**Document Version**: 1.0
-**Date**: December 2024
-**Authors**: Daniel Lemire and Francisco Geiman Thiesen
-
----
-
-## Table of Contents
-
-1. [Executive Summary](#1-executive-summary)
-2. [Experimental Environment](#2-experimental-environment)
-3. [Library Versions](#3-library-versions)
-4. [Benchmark Methodology](#4-benchmark-methodology)
-5. [Data Structure Definitions](#5-data-structure-definitions)
-6. [Per-Library Implementation Analysis](#6-per-library-implementation-analysis)
-7. [Output Equivalence Verification](#7-output-equivalence-verification)
-8. [Consolidated Results](#8-consolidated-results)
-9. [Threats to Validity](#9-threats-to-validity)
-10. [Conclusions](#10-conclusions)
-
----
-
-## 1. Executive Summary
-
-This document provides a rigorous, research-grade analysis of JSON serialization performance comparing simdjson's C++26 reflection-based serialization against five competing libraries. The benchmark measures the time to convert in-memory C++ data structures to JSON strings.
-
-**Key Findings:**
-- simdjson achieves **2.8-3.5 GB/s** on the Twitter dataset (81 KB output)
-- simdjson is **2.1-2.6x faster** than yyjson (the next fastest C library)
-- simdjson is **2.3-2.6x faster** than Rust/serde
-- simdjson is **20-23x faster** than nlohmann::json
-- All libraries produce semantically equivalent output (verified via output size matching)
-
----
-
-## 2. Experimental Environment
-
-### 2.1 Hardware Configuration
-
-| Component | Specification |
-|-----------|---------------|
-| CPU | Apple Silicon (aarch64) via Docker/OrbStack |
-| Architecture | ARM64 (aarch64-unknown-linux-gnu) |
-| Cores | 16 |
-| Threads per Core | 1 |
-| CPU Frequency | 2.0 GHz (virtualized) |
-| L1/L2 Cache | Apple Silicon unified cache |
-| RAM | 64 GB |
-| SIMD Support | NEON, ASIMD, AES, SHA1, SHA2, CRC32 |
-
-### 2.2 Software Configuration
-
-| Component | Version |
-|-----------|---------|
-| Operating System | Debian GNU/Linux 12 (bookworm) |
-| Kernel | 6.15.11-orbstack |
-| Container Runtime | Docker via OrbStack |
-| C++ Compiler | Bloomberg clang-p2996 (Clang 21.0.0git) |
-| C++ Standard | C++26 with `-freflection` |
-| Rust Compiler | rustc 1.63.0 |
-| Cargo | 1.65.0 |
-| Build Type | Release (-O2) |
-
-### 2.3 Execution Command
-
-The benchmarks were executed using the following command:
-
-```bash
-docker run --rm \
-  -v "/path/to/simdjson:/path/to/simdjson:Z" \
-  --privileged \
-  -w "/path/to/simdjson" \
-  debian12-clang-p2996-programming_station-for-randomperson-simdjson \
-  bash -c "./unified_benchmark.sh --serialization --clean"
-```
-
-The `unified_benchmark.sh` script configures CMake with:
-
-```bash
-CXX=/usr/local/bin/clang++ CC=/usr/local/bin/clang \
-CXXFLAGS="-std=c++26 -freflection" \
-cmake .. \
-    -DSIMDJSON_DEVELOPER_MODE=ON \
-    -DSIMDJSON_COMPETITION=ON \
-    -DSIMDJSON_STATIC_REFLECTION=ON \
-    -DSIMDJSON_USE_RUST=ON \
-    -DSIMDJSON_COMPETITION_RAPIDJSON=ON \
-    -DSIMDJSON_COMPETITION_YYJSON=ON \
-    -G "Unix Makefiles"
-```
-
----
-
-## 3. Library Versions
-
-| Library | Version | Language | Notes |
-|---------|---------|----------|-------|
-| simdjson | 4.2.3 | C++26 | With static reflection support |
-| nlohmann/json | 3.12.0 | C++11 | Header-only |
-| yyjson | 0.5.1 | C99 | High-performance C library |
-| reflect-cpp | 0.17.0 | C++20 | Reflection-based serialization |
-| serde | 1.0.x | Rust | De facto Rust standard |
-| serde_json | 1.0.x | Rust | JSON backend for serde |
-
----
-
-## 4. Benchmark Methodology
-
-### 4.1 Timing Infrastructure
-
-The benchmark uses a custom timing harness based on `std::chrono::steady_clock` with hardware performance counter support on Linux and Apple Silicon.
-
-**Core timing loop** (`benchmark_helper.h`):
-
-```cpp
-template <class function_type>
-event_aggregate bench(const function_type &function, size_t min_repeat = 10,
-                      size_t min_time_ns = 1000000000,
-                      size_t max_repeat = 100000) {
-  event_collector &collector = get_collector();
-  event_aggregate aggregate{};
-  size_t N = min_repeat;
-
-  for (size_t i = 0; i < N; i++) {
-    std::atomic_thread_fence(std::memory_order_acquire);
-    collector.start();
-    function();
-    std::atomic_thread_fence(std::memory_order_release);
-    event_count allocate_count = collector.end();
-    aggregate << allocate_count;
-
-    // Continue until minimum time (1 second) elapsed
-    if ((i + 1 == N) && (aggregate.total_elapsed_ns() < min_time_ns) &&
-        (N < max_repeat)) {
-      N *= 10;
-    }
-  }
-  return aggregate;
-}
-```
-
-**Key characteristics:**
-- **Minimum iterations**: 10 (warm-up)
-- **Minimum duration**: 1 second total
-- **Maximum iterations**: 100,000
-- **Memory barriers**: `std::atomic_thread_fence` prevents instruction reordering
-- **Result**: Average throughput across all iterations
-
-### 4.2 Throughput Calculation
-
-```cpp
-// Throughput in MB/s = (bytes * 1000) / elapsed_ns
-printf(" %5.2f MB/s ", bytes * 1000 / agg.elapsed_ns());
-```
-
-### 4.3 Output Verification
-
-Each benchmark verifies output correctness:
-
-```cpp
-measured_volume = output.size();
-if (measured_volume != output_volume) {
-  printf("mismatch\n");
-}
-```
-
----
-
-## 5. Data Structure Definitions
-
-### 5.1 Twitter Dataset
-
-All libraries serialize the identical C++ structure:
-
-```cpp
-// twitter_data.h
-struct User {
-  uint64_t id;
-  std::string name;
-  std::string screen_name;
-  std::string location;
-  std::string description;
-  bool verified;
-  uint64_t followers_count;
-  uint64_t friends_count;
-  uint64_t statuses_count;
-};
-
-struct Status {
-  std::string created_at;
-  uint64_t id;
-  std::string text;
-  User user;
-  uint64_t retweet_count;
-  uint64_t favorite_count;
-};
-
-struct TwitterData {
-  std::vector<Status> statuses;
-};
-```
-
-**Input**: `twitter.json` (631,515 bytes) - Real Twitter API response
-**Output**: 81,927 bytes (simplified schema serialization)
-
-### 5.2 CITM Catalog Dataset
-
-```cpp
-// citm_catalog_data.h
-struct CITMPrice {
-    uint64_t amount;
-    uint64_t audienceSubCategoryId;
-    uint64_t seatCategoryId;
-};
-
-struct CITMArea {
-    uint64_t areaId;
-    std::vector<uint64_t> blockIds;
-};
-
-struct CITMSeatCategory {
-    std::vector<CITMArea> areas;
-    uint64_t seatCategoryId;
-};
-
-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;
-};
-
-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;
-};
-
-struct CitmCatalog {
-    std::map<std::string, CITMEvent> events;        // 184 events
-    std::vector<CITMPerformance> performances;      // 243 performances
-};
-```
-
-**Input**: `citm_catalog.json` (1,727,204 bytes)
-**Output**: 496,682 bytes
-
----
-
-## 6. Per-Library Implementation Analysis
-
-### 6.1 simdjson (Static Reflection)
-
-**Implementation** (`benchmark_serialization_twitter.cpp:53-80`):
-
-```cpp
-// Fair allocation variant: allocates fresh buffer each iteration
-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();
-
-  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();
-               }));
-}
-```
-
-**Fairness Assessment**: ✅ **FAIR**
-- Allocates fresh `string_builder` each iteration
-- Matches allocation behavior of other libraries
-
-**Buffer Reuse Variant** (`benchmark_serialization_twitter.cpp:82-108`):
-
-```cpp
-// Optimized variant: reuses buffer across iterations
-template <class T> void bench_simdjson_static_reflection_reuse(T &data) {
-  simdjson::builder::string_builder sb;
-  // ... initial setup ...
-
-  pretty_print(sizeof(data), output_volume, "bench_simdjson_reuse_buffer",
-               bench([&data, &measured_volume, &output_volume, &sb]() {
-                 sb.clear();  // Clears content but retains allocated memory
-                 simdjson::builder::append(sb, data);
-                 // ...
-               }));
-}
-```
-
-**Fairness Assessment**: ⚠️ **OPTIMIZED** (not for cross-library comparison)
-- `sb.clear()` retains allocated memory, avoiding reallocation
-- Represents realistic production usage where buffers are reused
-- ~12-13% faster than fair variant
-
-### 6.2 nlohmann::json
-
-**Implementation** (`benchmark_serialization_twitter.cpp:155-169`):
-
-```cpp
-void bench_nlohmann(TwitterData &data) {
-  std::string output = nlohmann_serialize(data);
-  size_t output_volume = output.size();
-
-  volatile size_t measured_volume = 0;
-  pretty_print(1, output_volume, "bench_nlohmann",
-               bench([&data, &measured_volume, &output_volume]() {
-                 std::string output = nlohmann_serialize(data);
-                 measured_volume = output.size();
-               }));
-}
-```
-
-**Serialization function** (`nlohmann_twitter_data.h:60-63`):
-
-```cpp
-std::string nlohmann_serialize(const TwitterData &data) {
-  nlohmann::json j = data;
-  return j.dump();
-}
-```
-
-**Fairness Assessment**: ✅ **FAIR**
-- Fresh allocation each iteration
-- Uses standard nlohmann API (`dump()`)
-- No special optimizations applied
-
-### 6.3 yyjson
-
-**Implementation** (`benchmark_serialization_twitter.cpp:171-187`):
-
-```cpp
-void bench_yyjson(TwitterData &data) {
-  std::string output = yyjson_serialize(data);
-  size_t output_volume = output.size();
-
-  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();
-               }));
-}
-```
-
-**Serialization function** (`yyjson_twitter_data.h:97-143`):
-
-```cpp
-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);
-
-    // Manual field-by-field serialization
-    yyjson_mut_val *statuses_array = yyjson_mut_arr(doc);
-    for (const auto& status : data.statuses) {
-        yyjson_mut_val *status_obj = yyjson_mut_obj(doc);
-        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);
-        // ... more fields ...
-        yyjson_mut_arr_append(statuses_array, status_obj);
-    }
-    yyjson_mut_obj_add_val(doc, root, "statuses", statuses_array);
-
-    char *json_output = yyjson_mut_write(doc, 0, NULL);
-    std::string result(json_output);
-    free(json_output);
-    yyjson_mut_doc_free(doc);
-
-    return result;
-}
-```
-
-**Fairness Assessment**: ✅ **FAIR**
-- Fresh document allocation each iteration
-- Uses idiomatic yyjson mutable document API
-- Includes memory cleanup (`free`, `yyjson_mut_doc_free`)
-
-### 6.4 Rust/serde
-
-**Implementation** (`benchmark_serialization_twitter.cpp:40-51`):
-
-```cpp
-void bench_rust(serde_benchmark::TwitterData *data) {
-  const char * output = serde_benchmark::str_from_twitter(data);
-  size_t output_volume = strlen(output);
-
-  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);
-               }));
-}
-```
-
-**Rust FFI function** (`serde-benchmark/lib.rs:51-56`):
-
-```rust
-#[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()
-}
-```
-
-**Fairness Assessment**: ⚠️ **FAIR with documented overhead**
-- Fresh allocation each iteration (Rust `String` + `CString`)
-- FFI overhead includes:
-  1. Cross-language function call
-  2. `CString` allocation and copy from Rust `String`
-  3. Return value marshaling
-
-#### 6.4.1 Measured FFI Overhead (Twitter Dataset)
-
-We implemented a dedicated FFI overhead measurement that compares:
-1. Pure `serde_json::to_string()` timing (measured inside Rust)
-2. `serde_json::to_string()` + `CString` conversion (measured inside Rust)
-3. Full FFI call timing (measured from C++)
-
-**Measurement methodology** (`lib.rs`):
-
-```rust
-#[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;
-
-    // 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();
-        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();
-        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 }
-}
-```
-
-**Measured Results** (10,000 iterations, Twitter dataset):
-
-| Measurement | Time/iter | Throughput | Overhead |
-|------------|-----------|------------|----------|
-| Pure `serde_json::to_string()` | ~40,000 ns | ~1,930 MB/s | baseline |
-| + CString conversion | ~42,500 ns | ~1,840 MB/s | +5.4% |
-| + FFI call/return | ~45,000 ns | ~1,730 MB/s | +5.5% |
-| **Total FFI overhead** | ~5,000 ns | - | **~10%** |
-
-**Summary**:
-- **Measured FFI overhead: ~10%** (range: 9.4% - 11.0% across runs)
-- CString conversion contributes ~5.4% overhead (memory copy of 82KB string)
-- FFI call mechanics contribute ~5.5% overhead
-- **Pure Rust serde_json performance: ~1,930 MB/s** (vs ~1,730 MB/s reported)
-
-This means pure Rust/serde (without FFI) would be **~10% faster** than reported in our benchmarks. The comparison ratios should be adjusted accordingly:
-- simdjson vs pure Rust/serde: ~1.5x faster (instead of ~1.7x with FFI overhead)
-
-### 6.5 reflect-cpp
-
-**Implementation** (`benchmark_serialization_twitter.cpp:19-33`):
-
-```cpp
-void bench_reflect_cpp(TwitterData &data) {
-  std::string output = rfl::json::write(data);
-  size_t output_volume = output.size();
-
-  volatile size_t measured_volume = 0;
-  pretty_print(1, output_volume, "bench_reflect_cpp",
-               bench([&data, &measured_volume, &output_volume]() {
-                 std::string output = rfl::json::write(data);
-                 measured_volume = output.size();
-               }));
-}
-```
-
-**Fairness Assessment**: ✅ **FAIR**
-- Fresh allocation each iteration
-- Uses standard reflect-cpp API (`rfl::json::write`)
-- No special optimizations
-
----
-
-## 7. Output Equivalence Verification
-
-### 7.1 Twitter Dataset
-
-| Library | Output Size (bytes) | Match |
-|---------|---------------------|-------|
-| simdjson (static reflection) | 81,927 | ✅ Reference |
-| simdjson (to_json) | 81,927 | ✅ |
-| nlohmann::json | 81,927 | ✅ |
-| yyjson | 81,927 | ✅ |
-| Rust/serde | 81,927 | ✅ |
-| reflect-cpp | 81,927 | ✅ |
-
-**Verification**: All libraries produce identical output size, confirming semantic equivalence.
-
-### 7.2 CITM Catalog Dataset
-
-| Library | Output Size (bytes) | Match | Notes |
-|---------|---------------------|-------|-------|
-| simdjson (static reflection) | 496,682 | ✅ Reference | |
-| simdjson (to_json) | 496,682 | ✅ | |
-| nlohmann::json | 496,682 | ✅ | |
-| yyjson | 496,682 | ✅ | |
-| Rust/serde | 496,682 | ✅ | |
-| reflect-cpp | 476,270 | ⚠️ | -20,412 bytes |
-
-**reflect-cpp Discrepancy Analysis**:
-
-The 20,412-byte difference is due to `std::optional` handling:
-- simdjson/nlohmann output: `"logo":null` for empty optionals
-- reflect-cpp behavior: Omits empty optional fields entirely
-
-Both are valid JSON representations. For strict equivalence, note:
-- reflect-cpp has ~4% less data to write
-- This provides a small (likely <5%) performance advantage
-
----
-
-## 8. Consolidated Results
-
-### 8.1 Twitter Serialization (81,927 bytes output)
-
-**Multiple runs showing variance** (3 consecutive runs):
-
-| Library | Run 1 (MB/s) | Run 2 (MB/s) | Run 3 (MB/s) | Mean | Std Dev |
-|---------|-------------|-------------|-------------|------|---------|
-| simdjson (buffer reuse) | 3,460 | 3,245 | 3,393 | 3,366 | ±89 |
-| simdjson (fresh alloc) | 3,024 | 2,699 | 2,930 | 2,884 | ±136 |
-| simdjson to_json (reuse) | 2,660 | 2,892 | 2,998 | 2,850 | ±141 |
-| simdjson to_json (fresh) | 2,512 | 2,684 | 2,493 | 2,563 | ±86 |
-| yyjson | 1,346 | 1,370 | 1,309 | 1,342 | ±25 |
-| Rust/serde | 1,352 | 1,281 | 1,717 | 1,450 | ±190 |
-| reflect-cpp | 1,110 | 1,117 | 1,481 | 1,236 | ±173 |
-| nlohmann::json | 147 | 142 | 145 | 145 | ±2 |
-
-**Relative Performance** (vs simdjson fresh alloc):
-
-| Library | Throughput | Speedup |
-|---------|------------|---------|
-| **simdjson (buffer reuse)** | 3,366 MB/s | 1.17x |
-| **simdjson (fresh alloc)** | 2,884 MB/s | 1.00x (baseline) |
-| simdjson to_json (reuse) | 2,850 MB/s | 0.99x |
-| simdjson to_json (fresh) | 2,563 MB/s | 0.89x |
-| yyjson | 1,342 MB/s | 0.47x (2.1x slower) |
-| Rust/serde | 1,450 MB/s | 0.50x (2.0x slower) |
-| reflect-cpp | 1,236 MB/s | 0.43x (2.3x slower) |
-| nlohmann::json | 145 MB/s | 0.05x (19.9x slower) |
-
-### 8.2 CITM Catalog Serialization (496,682 bytes output)
-
-| Library | Throughput (MB/s) | vs simdjson |
-|---------|-------------------|-------------|
-| **simdjson (buffer reuse)** | 2,102 | 1.07x |
-| **simdjson (fresh alloc)** | 1,965 | 1.00x (baseline) |
-| simdjson to_json (fresh) | 1,913 | 0.97x |
-| simdjson to_json (reuse) | 1,864 | 0.95x |
-| Rust/serde | 1,078 | 0.55x (1.8x slower) |
-| yyjson | 921 | 0.47x (2.1x slower) |
-| reflect-cpp | 842 | 0.43x (2.3x slower)* |
-| nlohmann::json | 67 | 0.03x (29.3x slower) |
-
-*Note: reflect-cpp produces smaller output (476,270 bytes)
-
-### 8.3 Summary Claims (Conservative Estimates)
-
-Based on the fair comparison variants:
-
-| Claim | Twitter | CITM | Conservative |
-|-------|---------|------|--------------|
-| simdjson vs nlohmann | 19.9x | 29.3x | **~20x faster** |
-| simdjson vs yyjson | 2.1x | 2.1x | **~2x faster** |
-| simdjson vs Rust/serde (with FFI) | 2.0x | 1.8x | **~2x faster** |
-| simdjson vs Rust/serde (pure)* | ~1.5x | ~1.5x | **~1.5x faster** |
-| simdjson vs reflect-cpp | 2.3x | 2.3x | **~2x faster** |
-
-*Pure Rust/serde performance estimated by removing measured ~10% FFI overhead (see Section 6.4.1)
-
----
-
-## 9. Threats to Validity
-
-### 9.1 Internal Validity
-
-1. **Virtualization Overhead**: Benchmarks run in Docker on Apple Silicon via OrbStack. Native performance may differ.
-
-2. **Thermal Throttling**: Variance of ±10-15% observed between runs, likely due to thermal management in virtualized environment.
-
-3. **Memory Allocator**: All tests use the default system allocator. Custom allocators (jemalloc, tcmalloc) may affect relative performance.
-
-### 9.2 External Validity
-
-1. **Data Characteristics**: Twitter and CITM represent specific JSON patterns. Performance may vary with different data shapes (deeply nested, sparse, etc.).
-
-2. **String Content**: Test data contains UTF-8 text including emojis and non-ASCII characters. ASCII-only data may show different performance characteristics.
-
-3. **Platform**: Results are for ARM64 (Apple Silicon). x86-64 with AVX2/AVX-512 may show different relative performance.
-
-### 9.3 Construct Validity
-
-1. **Simplified Schema**: The Twitter benchmark uses a subset of the full schema (9 User fields vs 30+ in original). This may favor libraries optimized for smaller structures.
-
-2. **Rust FFI Overhead**: Rust numbers include FFI marshaling overhead. **Measured impact: ~10%** (see Section 6.4.1). Pure Rust applications would achieve ~1,930 MB/s vs the reported ~1,730 MB/s. This reduces the simdjson vs Rust/serde speedup from ~2x to ~1.5x when comparing against pure Rust performance.
-
-3. **reflect-cpp Output Size**: For CITM, reflect-cpp produces 4% smaller output due to optional field handling. This provides a small advantage.
-
----
-
-## 10. Conclusions
-
-### 10.1 Key Findings
-
-1. **simdjson with C++26 reflection achieves best-in-class serialization performance**, reaching 2.9-3.4 GB/s on the Twitter dataset.
-
-2. **Buffer reuse provides 12-17% improvement** over fresh allocation, representing realistic production performance.
-
-3. **simdjson is approximately 2x faster** than both yyjson (C) and Rust/serde, and **~20x faster** than nlohmann::json.
-
-4. **All benchmarks are methodologically fair**:
-   - Same data structures across all libraries
-   - Fresh allocation each iteration (for fair comparison)
-   - Output size verification confirms semantic equivalence
-
-### 10.2 Recommended Claims for Publication
-
-**Conservative (defensible under scrutiny)**:
-- "simdjson achieves 2.5+ GB/s JSON serialization throughput"
-- "simdjson is approximately 2x faster than yyjson"
-- "simdjson is approximately 1.5x faster than pure Rust/serde" (accounting for measured 10% FFI overhead)
-- "simdjson is approximately 20x faster than nlohmann::json"
-
-**With buffer reuse (realistic production)**:
-- "simdjson achieves 3+ GB/s with buffer reuse"
-- "Buffer reuse improves performance by 12-17%"
-
-**Important caveat for Rust comparison**:
-> The Rust/serde benchmark includes ~10% FFI overhead (measured). Pure Rust applications using serde_json directly would achieve approximately 1,930 MB/s, reducing simdjson's advantage from 2x to approximately 1.5x.
-
-### 10.3 Reproducibility
-
-All benchmarks can be reproduced using:
-
-```bash
-# Clone the repository
-git clone https://github.com/simdjson/simdjson.git
-cd simdjson
-git checkout francisco/ablation_study
-
-# Run benchmarks (requires Docker with Bloomberg clang-p2996 image)
-./p2996/run_docker.sh "./unified_benchmark.sh --serialization --clean"
-```
-
----
-
-## Appendix A: Raw Benchmark Output
-
-```
-=== Twitter Serialization Benchmark ===
-# Reading file /path/to/jsonexamples/twitter.json
-# output volume: 81927 bytes
-bench_nlohmann                                               :  147.15 MB/s
-# output volume: 81927 bytes
-bench_yyjson                                                 :  1486.64 MB/s
-# output volume: 81927 bytes
-bench_simdjson_static_reflection                             :  3070.12 MB/s
-# output volume: 81927 bytes
-bench_simdjson_reuse_buffer                                  :  3483.22 MB/s
-# output volume: 81927 bytes
-bench_simdjson_to                                            :  2855.68 MB/s
-# output volume: 81927 bytes
-bench_simdjson_to_reuse                                      :  2817.43 MB/s
-# output volume: 81927 bytes
-bench_rust                                                   :  1354.80 MB/s
-# output volume: 81927 bytes
-bench_reflect_cpp                                            :  1005.21 MB/s
-
-=== CITM Serialization Benchmark ===
-# output volume: 496682 bytes
-bench_nlohmann                                               :  67.24 MB/s
-# output volume: 496682 bytes
-bench_yyjson                                                 :  921.23 MB/s
-# output volume: 496682 bytes
-bench_simdjson_static_reflection                             :  1964.60 MB/s
-# output volume: 496682 bytes
-bench_simdjson_reuse_buffer                                  :  2102.01 MB/s
-# output volume: 496682 bytes
-bench_simdjson_to                                            :  1912.85 MB/s
-# output volume: 496682 bytes
-bench_simdjson_to_reuse                                      :  1864.27 MB/s
-# output volume: 496682 bytes
-bench_rust                                                   :  1077.79 MB/s
-# output volume: 476270 bytes
-bench_reflect_cpp                                            :  841.75 MB/s
-```
-
----
-
-## Appendix B: File Checksums
-
-For reproducibility verification:
-
-| File | Purpose | Lines |
-|------|---------|-------|
-| `benchmark/static_reflect/twitter_benchmark/benchmark_serialization_twitter.cpp` | Main Twitter benchmark | 302 |
-| `benchmark/static_reflect/twitter_benchmark/twitter_data.h` | C++ data structures | 32 |
-| `benchmark/static_reflect/twitter_benchmark/nlohmann_twitter_data.h` | nlohmann serializers | 70 |
-| `benchmark/static_reflect/twitter_benchmark/yyjson_twitter_data.h` | yyjson serializers | 145 |
-| `benchmark/static_reflect/serde-benchmark/lib.rs` | Rust/serde implementation | 241 |
-| `benchmark/static_reflect/benchmark_utils/benchmark_helper.h` | Timing infrastructure | 52 |

calculate_stats.py

@@ -1,174 +0,0 @@
-#!/usr/bin/env python3
-"""
-Calculate statistics from ablation study results.
-
-This script processes the CSV output from ablation_study.sh
-and generates formatted statistical summaries.
-"""
-
-import sys
-import csv
-import os
-from pathlib import Path
-
-def read_csv_results(filename):
-    """Read CSV results file and return data."""
-    results = []
-
-    try:
-        with open(filename, 'r') as f:
-            reader = csv.DictReader(f)
-            for row in reader:
-                results.append({
-                    'variant': row['Variant'],
-                    'mean': float(row['Mean_MB/s']),
-                    'stdev': float(row['StdDev']),
-                    'cv': float(row['CV%']),
-                    'runs': int(row['Runs']),
-                    'impact': float(row['Impact%']),
-                    'compile_time': float(row['CompileTime_s'])
-                })
-    except FileNotFoundError:
-        return None
-    except Exception as e:
-        print(f"Error reading {filename}: {e}")
-        return None
-
-    return results
-
-def print_results_table(title, results):
-    """Print formatted results table."""
-    if not results:
-        return
-
-    print(f"\n{'='*80}")
-    print(f"{title}")
-    print(f"{'='*80}")
-
-    # Print header
-    print(f"\n{'Variant':<25} {'Mean (MB/s)':<12} {'Std Dev':<10} {'CV (%)':<8} {'Impact':<12} {'Compile (s)':<12}")
-    print(f"{'-'*25} {'-'*12} {'-'*10} {'-'*8} {'-'*12} {'-'*12}")
-
-    for result in results:
-        variant_display = result['variant'].replace('_', ' ').title()
-        if result['variant'] == 'baseline':
-            variant_display = "**Baseline**"
-            impact_str = "Reference"
-        else:
-            impact_str = f"{result['impact']:+.1f}%"
-
-        print(f"{variant_display:<25} {result['mean']:<12.2f} ±{result['stdev']:<8.2f} "
-              f"{result['cv']:<8.2f} {impact_str:<12} {result['compile_time']:<12.2f}")
-
-def print_comparison_table(twitter_results, citm_results):
-    """Print comparison table between Twitter and CITM results."""
-    if not twitter_results or not citm_results:
-        return
-
-    print(f"\n{'='*80}")
-    print("Performance Comparison: Twitter vs CITM")
-    print(f"{'='*80}")
-
-    print(f"\n{'Optimization':<25} {'Twitter Impact':<15} {'CITM Impact':<15} {'Difference':<20}")
-    print(f"{'-'*25} {'-'*15} {'-'*15} {'-'*20}")
-
-    # Create lookup dictionaries
-    twitter_dict = {r['variant']: r for r in twitter_results}
-    citm_dict = {r['variant']: r for r in citm_results}
-
-    for variant in ['no_consteval', 'no_simd_escaping', 'no_fast_digits', 'no_branch_hints', 'linear_growth']:
-        if variant in twitter_dict and variant in citm_dict:
-            twitter_impact = twitter_dict[variant]['impact']
-            citm_impact = citm_dict[variant]['impact']
-
-            variant_display = variant.replace('_', ' ').title()
-            diff_abs = abs(citm_impact - twitter_impact)
-
-            if abs(twitter_impact) > 0.1:
-                diff_factor = citm_impact / twitter_impact
-                diff_str = f"{diff_factor:.1f}x"
-            else:
-                diff_str = "Different direction"
-
-            print(f"{variant_display:<25} {twitter_impact:>+14.1f}% {citm_impact:>+14.1f}% {diff_str:<20}")
-
-def print_summary_insights(twitter_results, citm_results):
-    """Print summary insights from the ablation study."""
-    print(f"\n{'='*80}")
-    print("Key Insights")
-    print(f"{'='*80}\n")
-
-    if twitter_results and citm_results:
-        # Find baseline performance
-        twitter_baseline = next((r['mean'] for r in twitter_results if r['variant'] == 'baseline'), 0)
-        citm_baseline = next((r['mean'] for r in citm_results if r['variant'] == 'baseline'), 0)
-
-        print(f"1. Baseline Performance:")
-        print(f"   - Twitter: {twitter_baseline:.2f} MB/s")
-        print(f"   - CITM: {citm_baseline:.2f} MB/s")
-        print(f"   - CITM is {((citm_baseline / twitter_baseline - 1) * 100):.1f}% slower than Twitter\n")
-
-        # Find most impactful optimizations
-        print(f"2. Most Impactful Optimizations:")
-
-        all_impacts = []
-        for r in twitter_results[1:]:  # Skip baseline
-            all_impacts.append(('Twitter', r['variant'], r['impact']))
-        for r in citm_results[1:]:  # Skip baseline
-            all_impacts.append(('CITM', r['variant'], r['impact']))
-
-        all_impacts.sort(key=lambda x: abs(x[2]), reverse=True)
-
-        for i, (bench, variant, impact) in enumerate(all_impacts[:5]):
-            variant_display = variant.replace('_', ' ').title()
-            print(f"   {i+1}. {variant_display} on {bench}: {impact:+.1f}%")
-
-        print(f"\n3. Variance Analysis:")
-        twitter_cv = next((r['cv'] for r in twitter_results if r['variant'] == 'baseline'), 0)
-        citm_cv = next((r['cv'] for r in citm_results if r['variant'] == 'baseline'), 0)
-        print(f"   - Twitter baseline CV: {twitter_cv:.2f}%")
-        print(f"   - CITM baseline CV: {citm_cv:.2f}%")
-        print(f"   - CITM shows {citm_cv / twitter_cv:.1f}x higher variance than Twitter")
-
-def main():
-    # Default to ablation_results directory
-    results_dir = "ablation_results"
-
-    # Allow custom directory as argument
-    if len(sys.argv) > 1:
-        results_dir = sys.argv[1]
-
-    # Check if directory exists
-    if not os.path.exists(results_dir):
-        print(f"Error: Results directory '{results_dir}' not found.")
-        print("Please run ablation_study.sh first.")
-        sys.exit(1)
-
-    # Read results files
-    twitter_file = os.path.join(results_dir, "twitter_ablation_results.csv")
-    citm_file = os.path.join(results_dir, "citm_ablation_results.csv")
-
-    twitter_results = read_csv_results(twitter_file)
-    citm_results = read_csv_results(citm_file)
-
-    if not twitter_results and not citm_results:
-        print("No results found. Please run ablation_study.sh first.")
-        sys.exit(1)
-
-    # Print results
-    if twitter_results:
-        print_results_table("Twitter Benchmark Results", twitter_results)
-
-    if citm_results:
-        print_results_table("CITM Benchmark Results", citm_results)
-
-    if twitter_results and citm_results:
-        print_comparison_table(twitter_results, citm_results)
-        print_summary_insights(twitter_results, citm_results)
-
-    print(f"\n{'='*80}")
-    print("Statistical Analysis Complete")
-    print(f"{'='*80}")
-
-if __name__ == "__main__":
-    main()

dependencies/CMakeLists.txt

@@ -12,7 +12,7 @@ cmake_dependent_option(SIMDJSON_GOOGLE_BENCHMARKS "compile the Google Benchmark
 if(SIMDJSON_GOOGLE_BENCHMARKS)
   CPMAddPackage(
         NAME google_benchmarks
-        URL https://github.com/google/benchmark/archive/refs/tags/v1.9.4.zip
+        URL https://github.com/google/benchmark/archive/refs/tags/v1.9.5.zip
         OPTIONS
         "BENCHMARK_ENABLE_TESTING OFF"
         "BENCHMARK_ENABLE_INSTALL OFF"
@@ -20,6 +20,14 @@ if(SIMDJSON_GOOGLE_BENCHMARKS)
   )
 endif()
 
+CPMAddPackage(
+        NAME counters
+        URL https://github.com/lemire/counters/archive/refs/tags/v3.1.0.zip
+        OPTIONS
+        "COUNTERS_BUILD_TESTS OFF"
+        "COUNTERS_INSTALL OFF"
+)
+
 CPMAddPackage(
         NAME simdjson-data
         URL https://github.com/simdjson/simdjson-data/archive/351949906abde446f0314bf79606fb5d884f5be7.zip

doc/basics.md

@@ -28,6 +28,9 @@ separate document](https://github.com/simdjson/simdjson/blob/master/doc/builder.
 - [UTF-8 validation (alone)](#utf-8-validation-alone)
 - [JSON Pointer](#json-pointer)
 - [JSONPath](#jsonpath)
+  * [Using `for_each_at_path_with_wildcard` for JSONPath Queries (On-Demand)](#using-for_each_at_path_with_wildcard-for-jsonpath-queries-on-demand)
+    + [Example Usage](#example-usage)
+- [C++20 Ranges Support](#c20-ranges-support)
 - [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)
@@ -56,7 +59,7 @@ Requirements
 The simdjson library is widely deployed in popular systems such as the Node.js runtime
 environment.
 
-- A recent compiler (LLVM clang 6 or better, GNU GCC 7.4 or better, Xcode 11 or better) on POSIX systems such as macOS, FreeBSD or Linux. We require that the compiler supports the C++11 standard or better. We test the library on a big-endian system (IBM s390x with Linux).
+- A recent compiler (LLVM clang 6 or better, GNU GCC 7.4 or better, Xcode 11 or better) on POSIX systems such as macOS, FreeBSD or Linux. We require that the compiler supports the C++11 standard or better. We test the library on a big-endian system (IBM s390x with Linux). We support [Fil-C, the memory-safe C/C++ compiler](https://fil-c.org).
 - Visual Studio 2017 or better. We support the LLVM clang compiler under Visual Studio (clang-cl) as well as the regular Visual Studio compiler. For better release performance (both compile time and execution time), we recommend Visual Studio users adopt LLVM (clang-cl). We discourage using GCC under Windows: there [is a long-running bug with GCC under Windows](https://gcc.gnu.org/bugzilla/show_bug.cgi?id=54412).
 
 Support for AVX-512 require a processor with AVX512-VBMI2 support (Ice Lake or better, AMD Zen 4 or better) under a 64-bit system and a recent compiler (LLVM clang 6 or better, GCC 8 or better, Visual Studio 2019 or better). You need a correspondingly recent assembler such as gas (2.30+) or nasm (2.14+): recent compilers usually come with recent assemblers. If you mix a recent compiler with an incompatible/old assembler (e.g., when using a recent compiler with an old Linux distribution), you may get errors at build time because the compiler produces instructions that the assembler does not recognize: you should update your assembler to match your compiler (e.g., upgrade binutils to version 2.30 or better under Linux) or use an older compiler matching the capabilities of your assembler.
@@ -161,52 +164,77 @@ The basics: loading and parsing JSON documents
 ----------------------------------------------
 
 The simdjson library allows you to navigate and validate JSON documents ([RFC 8259](https://www.tbray.org/ongoing/When/201x/2017/12/14/rfc8259.html)).
-As required by the standard, your JSON document should be in a Unicode (UTF-8) string. The whole
-string, from the beginning to the end, needs to be valid: we do not attempt to tolerate bad
-inputs before or after a document.
+Your JSON document should be a valid Unicode (UTF-8) string.
 
-For efficiency reasons, simdjson requires a string with a few bytes (`simdjson::SIMDJSON_PADDING`)
-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).
-
-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"`):
+To parse JSON, create a `ondemand::parser` and call its `iterate()` method on a padded input.
+The simplest way to load a JSON file is with `padded_string::load`:
 
 ```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
+auto json = padded_string::load("twitter.json");
+ondemand::document doc = parser.iterate(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")`.)
+For inline JSON strings, use the `_padded` suffix:
 
-If you prefer not to create your own `ondemand::parser` instance, you can access
-a thread-local version by calling `ondemand::parser.get_parser()`.
+```cpp
+ondemand::parser parser;
+auto json = "[1,2,3]"_padded;
+ondemand::document doc = parser.iterate(json);
+```
 
+If you are compiling with C++17 or better, you can use `simdjson::padded_input`
+which accepts any string-like input and handles padding automatically:
+
+```cpp
+ondemand::parser parser;
+std::string_view json = "[1,2,3]";
+simdjson::padded_input input(json);
+ondemand::document doc = parser.iterate(input);
+
+// Also works with std::string, considering reserved capacity
+std::string json_str = "[1,2,3]";
+json_str.reserve(100);  // Reserve extra space
+simdjson::padded_input input2(json_str);  // May avoid copying
+ondemand::document doc2 = parser.iterate(input2);
+```
+
+The simdjson library also accepts `std::string` instances directly---if the provided
+reference is non-const, it will allocate padding as needed:
+
+```cpp
+ondemand::parser parser;
+std::string json = "[1,2,3]";
+ondemand::document doc = parser.iterate(json);
+```
+
+By default, the simdjson library throws exceptions (`simdjson_error`) on errors. We omit `try`-`catch` clauses from our illustrating examples: if you omit `try`-`catch` in your code, an uncaught exception will halt your program. It is also possible to use simdjson without generating exceptions, and you may even build the library without exception support at all. See [Error handling](#error-handling) for details.
+
+
+### Advanced input options
+
+This section covers additional ways to provide JSON input to simdjson, including
+options for fine-grained control over padding and memory.
+
+**Thread-local parser.** If you prefer not to create your own `ondemand::parser` instance, you can access
+a thread-local version by calling `ondemand::parser.get_parser()`:
 
 ```cpp
 ondemand::document doc = ondemand::parser.get_parser().iterate(json);
 ```
 
-However, you should be careful because a parser instance can only be used for one
-document at a time, thus it is only applicable when you are only parsing one
+A parser instance can only be used for one document at a time, so
+the thread-local parser is only applicable when you parse one
 document per thread at any one time.
 
-You can also create a padded string---and call `iterate()`:
+**`padded_input` details (C++17+).** The actual padding only occurs when the JSON string ends near the boundary of a memory page, which is
+uncommon. Using a `simdjson::padded_input` is safe although sanitizers and tools like valgrind
+might report illegal reads (which are safe in our case because they remain in the mapped page). You should avoid `simdjson::padded_input`
+on systems without a page size of at least 4096: virtually all systems qualify except for
+some niche embedded systems running custom operating systems. Standard Linux, Windows, macOS, Android, iOS, etc., are all fine. Note that, most times, a `simdjson::padded_input` instance will not copy the data and will only act
+as a view (it does not own the memory).
 
-```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
-```
-
-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:
+**User-managed buffers.** 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:
 
 ```cpp
 ondemand::parser parser;
@@ -215,60 +243,99 @@ strcpy(json, "[1]");
 ondemand::document doc = parser.iterate(json, strlen(json), sizeof(json));
 ```
 
-The simdjson library will also accept `std::string` instances. If the provided
-reference is non-const, it will allocate padding as needed.
-
-You can copy your data directly on a `simdjson::padded_string` as follows:
+**Copying into a `padded_string`.** You can copy your data directly into a `simdjson::padded_string`:
 
 ```cpp
 const char * data = "my data"; // 7 bytes
 simdjson::padded_string my_padded_data(data, 7); // copies to a padded buffer
 ```
 
-Or as follows...
+Or from a `std::string`:
 
 ```cpp
 std::string data = "my data";
 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:
-
-
-```cpp
-ondemand::document doc = parser.iterate(my_padded_data);
-```
-
-Whenever you pass an `std::string` reference to `parser::iterate`,
-the parser will access the bytes beyond the end of
+**`std::string` and sanitizer warnings.** Whenever you pass an `std::string` reference to `parser::iterate`,
+the parser may access bytes beyond the end of
 the string but before the end of the allocated memory (`std::string::capacity()`).
-If you are using a sanitizer that checks for reading uninitialized bytes or `std::string`'s
-container-overflow checks, you may encounter sanitizer warnings.
-You can safely ignore these warnings. Or you can call `simdjson::pad(std::string&)` to pad the
-string with `SIMDJSON_PADDING` spaces: this function returns a `simdjson::padding_string_view` which can be be passed to the parser's iterator function:
+Sanitizers that check for reading uninitialized bytes may produce warnings.
+You can safely ignore these warnings, or call `simdjson::pad(std::string&)` to pad the
+string explicitly:
 
 ```cpp
 std::string json = "[1]";
 ondemand::document doc = parser.iterate(simdjson::pad(json));
 ```
 
-We recommend against creating many `std::string` or many `std::padding_string` instances in your application to store your JSON data.
+We recommend against creating many `std::string` or many `std::padded_string` instances in your application to store your JSON data.
 Consider reusing the same buffers and limiting memory allocations.
 
-By default, the simdjson library throws exceptions (`simdjson_error`) on errors. We omit `try`-`catch` clauses from our illustrating examples: if you omit `try`-`catch` in your code, an uncaught exception will halt your program. It is also possible to use simdjson without generating exceptions, and you may even build the library without exception support at all. See [Error handling](#error-handling) for details.
+**Memory-file mapping.** You can use `simdjson::padded_memory_map` to create a
+`simdjson::padded_string_view` from a file on disk. On POSIX systems (Linux,
+macOS, BSD, ...) it uses `mmap` for true zero-copy access and is always
+available. On Windows it is an **opt-in** feature because it relies on the
+`CreateFileMapping2` / `MapViewOfFile3` APIs (Windows 10, version 1803 or
+later) which are exported from `onecore.lib` rather than the default
+`kernel32.lib`. To enable it, you must satisfy **all** of the following:
 
-Some users may want to browse code along with the compiled assembly. You want to check out the following lists of examples:
+1. Building simdjson with `-DSIMDJSON_ENABLE_MEMORY_FILE_MAPPING_ON_WINDOWS=ON`, or
+   defining `SIMDJSON_ENABLE_MEMORY_FILE_MAPPING_ON_WINDOWS=1` and raising
+   `NTDDI_VERSION` to at least `NTDDI_WIN10_RS4` (Windows 10, version 1803)
+   and linking `onecore.lib` manually if you are consuming simdjson as a
+   pre-built library.
+2. `#include <windows.h>` before including simdjson, in every translation
+   unit that uses `padded_memory_map`.
 
-* [simdjson examples with errors handled through exceptions](https://godbolt.org/z/98Kx9Kqjn)
-* [simdjson examples with errors without exceptions](https://godbolt.org/z/PKG7GdbPo)
+The Windows implementation then uses `CreateFileMapping2` / `MapViewOfFile3`
+for true zero-copy access whenever possible, with a transparent
+buffered-read fallback for files that end too close to a page boundary.
 
-*Windows-specific*:  Windows users who need to read files with
+The availability of the class can be tested with the preprocessor macro
+`SIMDJSON_HAS_PADDED_MEMORY_MAP`.
+
+```cpp
+#ifdef _WIN32
+#include <windows.h> // Must come BEFORE <simdjson.h> on Windows
+#endif
+#include "simdjson.h"
+// ...
+simdjson::padded_memory_map map(myfilename);
+if (!map.is_valid()) { /* handle error */ }
+simdjson::padded_string_view view = map.view();
+ondemand::document doc = parser.iterate(view);
+```
+
+**Windows-specific notes.** 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 who need to read files with
 non-ANSI characters in the name should set their code page to
 UTF-8 (65001). This should be the default with Windows 11 and better.
 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.
 
+Some users may want to browse code along with the compiled assembly:
+
+* [simdjson examples with errors handled through exceptions](https://godbolt.org/z/98Kx9Kqjn)
+* [simdjson examples with errors without exceptions](https://godbolt.org/z/PKG7GdbPo)
+
+**Summary of input types:**
+
+
+| Input Type / Method                          | Padding Requirement                                                                 | How Padding is Handled                                                                 | Ownership / Copying                          | Notes / Warnings                                                                 |
+|----------------------------------------------|-------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------|----------------------------------------------|----------------------------------------------------------------------------------|
+| `padded_string::load("file.json")`           | Automatic (SIMDJSON_PADDING extra bytes)                                           | Library allocates padded buffer and loads file into it                                 | Owned by `padded_string`                     | Recommended for files; safest and simplest.                                      |
+| `"...json..."_padded` literal                | Automatic (built-in padding)                                                        | Creates `padded_string` with padding                                                   | Owned by `padded_string`                     | Convenient for small hardcoded JSON.                                             |
+| `simdjson::padded_input` (C++17+)            | Automatic when needed                                                               | Adds padding **only** if the string ends near a memory page boundary. For `std::string`, considers `capacity()` | Usually a non-owning view (no copy most times) | Safe on standard OS (page size ≥ 4096). May trigger sanitizer/valgrind warnings (harmless). Avoid on niche embedded systems. |
+| User buffer with explicit padding            | Must have at least `SIMDJSON_PADDING` extra allocated bytes after JSON content     | Pass via `iterate(ptr, json_length, total_allocated_size)` or `padded_string_view`     | User-owned (no copy)                         | Use `char buf[len + SIMDJSON_PADDING]`. Library reads (but never writes) into padding. |
+| `std::string` (non-const)                    | Library checks `capacity()`                                                         | If insufficient, library may allocate a padded copy                                    | May copy (depends on capacity)               | Can trigger sanitizer warnings on uninitialized bytes. Use `simdjson::pad(json)` to avoid. |
+| `simdjson::pad(std::string&)`                | Adds padding if needed                                                              | Returns `padded_string_view` pointing to the (possibly resized) string                 | References original string                   | Recommended to silence sanitizers when using `std::string`.                      |
+| `padded_string(data, length)` or `padded_string(std::string)` | Automatic (copies into padded buffer)                                              | Explicit copy into owned padded buffer                                                 | Owned by `padded_string`                     | Safe when you want full ownership and padding guaranteed.                        |
+| `padded_string_view` (manual)                | User guarantees `SIMDJSON_PADDING` extra bytes after the viewed length             | User provides pointer + length + capacity                                              | Non-owning view                              | Low-level; requires careful buffer management.                                   |
+| Memory-mapped file (`padded_memory_map`)     | Automatic via mapping / padded read                                                 | Creates view with sufficient padding                                                   | Non-owning (tied to map lifetime)            | Always available on POSIX (zero-copy `mmap`). On Windows, opt-in via `-DSIMDJSON_ENABLE_MEMORY_FILE_MAPPING_ON_WINDOWS=ON` (requires Windows 10 1803+ and links `onecore.lib`) and `#include <windows.h>` before simdjson; uses `CreateFileMapping2` + `MapViewOfFile3`. |
+
+
 Documents are iterators
 -----------------------
 
@@ -354,7 +421,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
@@ -366,6 +439,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
 ---------------------
 
@@ -409,7 +486,7 @@ support for users who avoid exceptions. See [the simdjson error handling documen
 * **Extracting Values:** You can cast a JSON element to a native type:
   `double(element)`. This works for `std::string_view`, double, uint64_t, int64_t, bool,
   ondemand::object and ondemand::array. We also have explicit methods such as `get_string()`, `get_double()`,
-  `get_uint64()`, `get_int64()`, `get_bool()`, `get_object()` and `get_array()`. After a cast or an explicit method,
+  `get_uint64()`, `get_int64()`, `get_uint32()`, `get_int32()`, `get_bool()`, `get_object()` and `get_array()`. After a cast or an explicit method,
   the number, string or boolean will be parsed, or the initial `{` or `[` will be verified for `ondemand::object` and `ondemand::array`. An exception may be thrown if
   the cast is not possible: the error code is `simdjson::INCORRECT_TYPE` (see [Error handling](#error-handling)). Importantly, when getting an ondemand::object or ondemand::array instance, its content is
   not validated: you are only guaranteed that the corresponding initial character (`{` or `[`) is present. Thus,
@@ -419,8 +496,8 @@ support for users who avoid exceptions. See [the simdjson error handling documen
   pass `true` (`get_string(true)`) as a parameter to get replacement characters where errors
   occur. If you somehow need to access non-UTF-8 strings in a lossless manner
   (e.g., if you strings contain unpaired surrogates), you may use the `get_wobbly_string()` function to get a string in the [WTF-8 format](https://simonsapin.github.io/wtf-8).
-  When calling `get_uint64()` and `get_int64()`, if the number does not fit in a corresponding
-  64-bit integer type, it is also considered an error. When parsing numbers or other scalar values, the library checks
+  When calling `get_uint64()`, `get_int64()`, `get_uint32()` or `get_int32()`, if the number does not fit in the
+  corresponding integer type, it is also considered an error (`NUMBER_OUT_OF_RANGE`). When parsing numbers or other scalar values, the library checks
   that the value is followed by an expected character, thus you *may* get a number parsing error when accessing the digits
   as an integer in the following strings: `{"number":12332a`, `{"number":12332\0`, `{"number":12332` (the digits appear at the end). We always abide by the [RFC 8259](https://www.tbray.org/ongoing/When/201x/2017/12/14/rfc8259.html) JSON specification so that, for example, numbers prefixed by the `+` sign are in error.
 
@@ -437,8 +514,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.
@@ -451,13 +528,17 @@ 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. 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
+  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
@@ -1269,10 +1350,6 @@ You can also use the custom `Car` type as part of a template such as `std::vecto
   simdjson::ondemand::parser parser;
   simdjson::ondemand::document doc = parser.iterate(json);
   std::vector<Car> cars(doc);
-  // visual studio users need an explicit call:
-  //   std::vector<Car> cars = doc.get<std::vector<Car>>();
-  // because the compiler does not know whether to convert
-  // doc to an unsigned int or to a vector.
   for(Car& c : cars) {
     std::cout << c.year << std::endl;
   }
@@ -1366,6 +1443,8 @@ With this code, deserializing an `std::list<Car>` instance would capture only th
 that are not made by Toyota.
 
 
+**Performance tip**: You will get better performance if you order the attributes (make, model)
+in the order they appear in the JSON document.
 
 
 ### 3. Using static reflection (C++26)
@@ -1442,6 +1521,10 @@ void f() {
 }
 ```
 
+
+**Performance tip**: You will get better performance if you order the attributes (make, model)
+in the order they appear in the JSON document.
+
 #### Special cases
 
 However, there are instances where the construction cannot
@@ -1519,6 +1602,10 @@ type without a document instance like so:
 Car car = simdjson::from(json);
 ```
 
+The string must be a `simdjson::padded_string_view`, which can be created from an std::string
+instance with `simdjson::pad()` function, from a `simdjson::padded_string` instance, or string literal using the `_padded`  user-defined literal.
+
+
 You can also use the `simdjson::from` syntax without exceptions, like so:
 ```cpp
 Car car;
@@ -1759,15 +1846,15 @@ 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)
+## Using `for_each_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 `for_each_at_path_with_wildcard` function in simdjson extends the JSONPath querying capabilities by supporting wildcard expressions (`*`) in JSON paths. It calls a user-provided callback for each matching element, avoiding the need to materialize all results into a vector. 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.
+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 callback is simply never called. For instance, querying `$.empty_object.*` or `$.empty_array.*` will yield no callbacks.
 
 ### Example Usage
 
-Here is an example demonstrating the use of `at_path_with_wildcard`:
+Here is an example demonstrating the use of `for_each_at_path_with_wildcard`:
 
 ```cpp
 simdjson::padded_string json_string = R"(
@@ -1796,31 +1883,86 @@ 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;
-    }
-  }
-}
+auto error = doc.for_each_at_path_with_wildcard("$.address.*",
+    [](ondemand::value value) {
+      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;
-    }
-  }
-}
+doc.for_each_at_path_with_wildcard("$.phoneNumbers[*].numbers[*]",
+    [](ondemand::value value) {
+      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.
 
+## C++20 Ranges Support
+
+When compiling with C++20 (or later), you can use `std::ranges` with the On-Demand API
+via the `get_range()` helper. This enables use of range adaptors such as `std::views::transform`.
+
+```cpp
+#include "simdjson.h"
+#include <ranges>
+#include <string>
+#include <vector>
+
+auto json = R"([
+  { "name": "Alice", "age": 30 },
+  { "name": "Bob",   "age": 25 },
+  { "name": "Carol", "age": 35 }
+])"_padded;
+
+ondemand::parser parser;
+auto doc = parser.iterate(json);
+auto arr = doc.get_array();
+
+// Use std::views::transform to extract names
+auto names = ondemand::get_range(arr)
+  | std::views::transform([](auto elem) -> std::string {
+      return std::string(std::string_view(elem["name"]));
+    });
+
+for (auto name : names) {
+  std::cout << name << std::endl;  // Alice, Bob, Carol
+}
+```
+
+The `get_range()` and `get_key_value_range()` functions wrap an `ondemand::array`
+or `ondemand::object` in a `std::ranges::view` that satisfies `std::ranges::input_range`.
+They work with both exception and non-exception code:
+
+```cpp
+// With exceptions:
+auto range = ondemand::get_range(doc.get_array());
+
+// Without exceptions:
+ondemand::array arr;
+if (doc.get_array().get(arr) == SUCCESS) {
+  auto range = ondemand::get_range(arr);
+  for (auto elem : range) { /* ... */ }
+}
+```
+
+Object iteration uses `get_key_value_range()` and yields `simdjson_result<ondemand::field>` elements:
+
+```cpp
+auto obj = doc.get_object();
+for (auto field_result : ondemand::get_key_value_range(obj)) {
+  std::cout << field_result.key() << std::endl;
+}
+```
+
+The range wrappers are zero-cost: they forward directly to the underlying
+On-Demand iterators with no value buffering or extra per-element overhead.
+
 ## 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

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
 ---------------------------
@@ -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

@@ -32,6 +32,21 @@ your code with the `SIMDJSON_STATIC_REFLECTION` macro set:
 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.
 
+For convenience, you can also use the `""_json` user-defined literal operator, which is available in the `simdjson::literals` namespace:
+
+```cpp
+using namespace simdjson::literals;
+
+constexpr auto cfg = R"(
+{
+    "port": 8080,
+    "host": "localhost"
+}
+)"_json;
+```
+
+Alternatively, you can use the qualified name `simdjson::literals::operator""_json`.
+
 
 | JSON type      | C++ type                         |
 |----------------|----------------------------------|
@@ -61,6 +76,8 @@ You can do so, at compile-time, as follows:
 
 
 ```cpp
+using namespace simdjson::literals;
+
 constexpr auto cfg = R"(
 
 {
@@ -79,6 +96,8 @@ constexpr auto cfg = R"(
 You can nest objects and arrays:
 
 ```cpp
+using namespace simdjson::literals;
+
 constexpr auto data = R"(
 
 {
@@ -98,6 +117,8 @@ constexpr auto data = R"(
 Top-level arrays are allowed:
 
 ```cpp
+using namespace simdjson::literals;
+
 constexpr auto arr = R"(
 
 [1, 2, 3]
@@ -116,6 +137,8 @@ want to check that it conforms to your expectation. You can do so with concepts.
 Let us consider this example:
 
 ```cpp
+    using namespace simdjson::literals;
+
     constexpr auto config = R"(
 
     [
@@ -128,7 +151,7 @@ Let us consider this example:
 ```
 
 You might want to ensure that the result is an array of persons. You can define your
-expection with concepts like so:
+expectation with concepts like so:
 
 ```cpp
 template <typename T>

doc/dom.md

@@ -62,6 +62,8 @@ 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")`.)
 
@@ -123,6 +125,42 @@ 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:**
+You can use `simdjson::padded_memory_map` to create a `simdjson::padded_string_view`
+from a file on disk without copying the file contents into your own buffer.
+On POSIX systems (Linux, macOS, BSD, ...) it uses `mmap` for true zero-copy
+access. On Windows it is available as an **opt-in** feature and requires:
+
+1. Building simdjson with `-DSIMDJSON_ENABLE_MEMORY_FILE_MAPPING_ON_WINDOWS=ON`, or
+   defining `SIMDJSON_ENABLE_MEMORY_FILE_MAPPING_ON_WINDOWS=1` and raising
+   `NTDDI_VERSION` to at least `NTDDI_WIN10_RS4` (Windows 10, version 1803)
+   and linking `onecore.lib` manually if you are consuming simdjson as a
+   pre-built library.
+2. `#include <windows.h>` before `#include "simdjson.h"` in every
+   translation unit where you want to use `padded_memory_map`.
+
+When enabled on Windows, the implementation uses `CreateFileMapping2` and
+`MapViewOfFile3` for true zero-copy mapping whenever the file does not end
+within `SIMDJSON_PADDING` bytes of a page boundary; otherwise it falls back
+to reading the file into a padded heap buffer. If those requirements are
+not met, the class is not declared and the code below will fail to compile.
+
+```cpp
+#ifdef _WIN32
+#include <windows.h> // Must come BEFORE <simdjson.h> on Windows
+#endif
+#include "simdjson.h"
+// ...
+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
 ---------------------
 
@@ -150,6 +188,23 @@ Once you have an element, you can navigate it with idiomatic C++ iterators, oper
   `SIMDJSON_MINUS_ZERO_AS_FLOAT` to `1` when building simdjson, you can get that `-0` is mapped to `-0.0`
   as in JavaScript. You can get the desired effect by building simdjson with cmake setting the
   `SIMDJSON_MINUS_ZERO_AS_FLOAT` to on: `cmake -B build -D SIMDJSON_MINUS_ZERO_AS_FLOAT=ON`.
+* **Big Integer Support (opt-in):** By default, integers that exceed the 64-bit range cause parsing to fail with `BIGINT_ERROR`. You can opt in to big integer support so that these numbers are stored as raw digit strings on the tape instead:
+  ```cpp
+  simdjson::dom::parser parser;
+  parser.number_as_string(true); // opt-in, default false
+  simdjson::dom::element doc;
+  auto error = parser.parse("[1, 123456789012345678901]"_padded).get(doc);
+  if (error) { std::cerr << error << std::endl; return EXIT_FAILURE; }
+  for (simdjson::dom::element elem : doc) {
+    if (elem.is_bigint()) {
+      std::string_view digits;
+      error = elem.get_bigint().get(digits);
+      if (error) { std::cerr << error << std::endl; return EXIT_FAILURE; }
+      std::cout << "big integer: " << digits << std::endl;
+    }
+  }
+  ```
+  When enabled, big integers have type `element_type::BIGINT`. Calling `get_int64()`, `get_uint64()`, or `get_double()` on a big integer returns `INCORRECT_TYPE`. Normal numbers (int64, uint64, double) are unaffected.
 * **Field Access:** To get the value of the "foo" field in an object, use `object["foo"]`.
 * **Array Iteration:** To iterate through an array, use `for (auto value : array) { ... }`. If you
   know the type of the value, you can cast it right there, too! `for (double value : array) { ... }`
@@ -162,7 +217,7 @@ Once you have an element, you can navigate it with idiomatic C++ iterators, oper
 * **Array and Object size** Given an array or an object, you can get its size (number of elements or keys)
   with the `size()` method.
 * **Checking an Element Type:** You can check an element's type with `element.type()`. It
-  returns an `element_type` with values such as `simdjson::dom::element_type::ARRAY`, `simdjson::dom::element_type::OBJECT`, `simdjson::dom::element_type::INT64`,  `simdjson::dom::element_type::UINT64`,`simdjson::dom::element_type::DOUBLE`, `simdjson::dom::element_type::STRING`, `simdjson::dom::element_type::BOOL` or, `simdjson::dom::element_type::NULL_VALUE`.
+  returns an `element_type` with values such as `simdjson::dom::element_type::ARRAY`, `simdjson::dom::element_type::OBJECT`, `simdjson::dom::element_type::INT64`,  `simdjson::dom::element_type::UINT64`,`simdjson::dom::element_type::DOUBLE`, `simdjson::dom::element_type::STRING`, `simdjson::dom::element_type::BOOL`, `simdjson::dom::element_type::NULL_VALUE` or, `simdjson::dom::element_type::BIGINT` (when big integer support is enabled).
 * **Output to streams and strings:** Given a document or an element (or node) out of a JSON document, you can output a minified string version using the C++ stream idiom (`out << element`). You can also request the construction of a minified string version (`simdjson::minify(element)`) or a prettified string version (`simdjson::prettify(element)`). Numbers are serialized as 64-bit floating-point numbers (`double`).
 
 ### Examples
@@ -735,6 +790,9 @@ void basics_treewalk_1() {
 }
 ```
 
+Notice that we do not include `dom::element_type::BIGINT` in this example
+as `dom::element_type::BIGINT` type is only generated if the parser was
+set to support big integers (`parser.number_as_string(true)`).
 
 
 Reusing the parser for maximum efficiency
@@ -847,6 +905,19 @@ simdjson::dom::element element = parser.parse(padded_json_copy.get(), json_len,
 
 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.
 
+If you are compiling your project with C++17 or better, you can use a `simdjson::padded_input`:
+
+```cpp
+simdjson::dom::parser parser;
+std::string_view json = "[1,2,3]";
+simdjson::padded_input input(json); // Automatically pads if needed
+simdjson::dom::element element = parser.parse(input);
+```
+
+The actual padding only occurs if the JSON string ends near the boundary of a memory page, which is uncommon. Using a `simdjson::padded_input` is safe although sanitizers and tools like valgrind might report illegal reads (which are safe in our case because they remain in the mapped page). You should avoid `simdjson::padded_input` on systems without a page size of at least 4096: virtually all systems qualify except for some niche embedded systems running custom operating systems. Standard Linux, Windows, macOS, Android, iOS, etc., are all fine.  Note that, most times, an `simdjson::padded_input` instance will not copy the data and will only act
+as a view (it does not own the memory).
+
+
 Performance Tips
 ---------------------
 

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).

doc/iterate_many.md

@@ -22,10 +22,12 @@ Contents
   - [Threads](#threads)
 - [Support](#support)
 - [API](#api)
+- [Streaming directly from a memory-mapped file](#streaming-directly-from-a-memory-mapped-file)
 - [Use cases](#use-cases)
 - [Tracking your position](#tracking-your-position)
 - [Incomplete streams](#incomplete-streams)
 - [C++20 features](#c20-features)
+- [C++26 features (static reflection)](#c26-features-static-reflection)
 
 Motivation
 -----------
@@ -132,7 +134,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 simdjson!
+- [Record separator-delimited JSON (RFC 7464)](https://tools.ietf.org/html/rfc7464)
 - [More on Wikipedia...](https://en.wikipedia.org/wiki/JSON_streaming)
 
 API
@@ -154,6 +156,86 @@ for (auto doc : docs) {
 
 See [basics.md](basics.md#newline-delimited-json-ndjson-and-json-lines) for an overview of the API.
 
+
+Streaming directly from a memory-mapped file
+--------------------------------------------
+
+When your input is a large NDJSON / JSON-lines file on disk, the most efficient
+way to feed `iterate_many` is to use `simdjson::padded_memory_map`. It returns
+a `padded_string_view` with the right amount of trailing padding, so you can
+hand it straight to `iterate_many` without ever copying the file contents into
+your own buffer.
+
+`padded_memory_map` is available on POSIX systems (Linux, macOS, BSD, ...) by
+default. On Windows it is an **opt-in** feature with the following
+requirements:
+
+1. Build simdjson with `-DSIMDJSON_ENABLE_MEMORY_FILE_MAPPING_ON_WINDOWS=ON`, or — if
+   you consume simdjson as a pre-built library — define
+   `SIMDJSON_ENABLE_MEMORY_FILE_MAPPING_ON_WINDOWS=1`, raise `NTDDI_VERSION` to at
+   least `NTDDI_WIN10_RS4` (`0x0A000005`, Windows 10 version 1803), and
+   add `onecore.lib` to your link line yourself. The Windows
+   implementation uses the modern memory APIs `CreateFileMapping2` /
+   `MapViewOfFile3`, which are available starting with that version of
+   Windows and are exported by `onecore.lib`.
+2. `#include <windows.h>` before `#include "simdjson.h"` in every
+   translation unit where you want to use `padded_memory_map`. simdjson
+   deliberately does not pull in `<windows.h>` itself, so the class is
+   only declared when the Win32 types are already visible.
+
+If either requirement is not met on Windows, the `padded_memory_map` class is
+not declared at all and any code that references it fails to compile with an
+"unknown identifier" error. The availability of the class can be tested with
+the macro `SIMDJSON_HAS_PADDED_MEMORY_MAP`.
+
+On POSIX, `padded_memory_map` uses `mmap` to map the file directly into
+memory with zero copies. On Windows (when enabled), it uses
+`CreateFileMapping2` + `MapViewOfFile3` for true zero-copy mapping
+whenever the file does not end within `SIMDJSON_PADDING` bytes of a page
+boundary; for those rare cases, it transparently falls back to reading
+the file into a heap-allocated padded buffer so that the returned view
+always has `SIMDJSON_PADDING` accessible zero bytes after the file content.
+
+```cpp
+#ifdef _WIN32
+#include <windows.h> // Must come BEFORE <simdjson.h> on Windows
+#endif
+#include "simdjson.h"
+
+// ...
+
+simdjson::padded_memory_map map("huge_stream.ndjson");
+if (!map.is_valid()) { /* file missing, unreadable, too large, ... */ return; }
+
+simdjson::ondemand::parser parser;
+simdjson::ondemand::document_stream stream;
+auto error = parser.iterate_many(map.view()).get(stream);
+if (error) { std::cerr << error << std::endl; return; }
+
+for (auto doc : stream) {
+  // process each JSON document in the stream
+  std::cout << doc << std::endl;
+}
+```
+
+Important lifetime rule: the `padded_string_view` returned by `map.view()` is
+only valid while the `padded_memory_map` instance is alive, so keep `map`
+alive for as long as you are iterating the stream.
+
+The file must not be modified while the memory map is in use. If you need a
+fully independent copy of the data, use `simdjson::padded_string::load(...)`
+instead.
+
+If you prefer single-document parsing on a memory-mapped file, the same
+pattern applies to `parser.iterate(...)`:
+
+```cpp
+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/):
@@ -264,39 +346,131 @@ Importantly, you should only call `truncated_bytes()` after iterating through al
 Comma-separated documents
 -----------
 
-We also support comma-separated documents, but with some performance limitations. The `iterate_many` function  takes in an option to allow parsing of comma separated documents (which defaults on false). In this mode, the entire buffer is processed in one batch. Therefore, the total size of the document should not exceed the maximal capacity of the parser (4 GB). This mode also effectively disallow multithreading. It is therefore mostly suitable for not "very large" inputs. In this mode, the batch_size parameter
-is effectively ignored, as it is set to at least the document size.
-
-Example:
+To parse comma-separated documents like `{"a":1},{"b":2},{"c":3}`, use the `stream_format::comma_delimited` parameter:
 
 ```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;
-    // We pass '32' as the batch size, but it is a bogus parameter because, since
-    // we pass 'true' to the allow_comma parameter, the batch size will be set to at least
-    // the document size.
-    auto error = parser.iterate_many(json, 32, true).get(doc_stream);
-    if (error) { std::cerr << error << std::endl; return; }
-    for (auto doc : doc_stream) {
-        std::cout << doc.type() << std::endl;
-    }
- ```
-
- This will print:
-
+auto json = R"({"a":1},{"b":2},{"c":3})"_padded;
+ondemand::parser parser;
+ondemand::document_stream stream;
+auto error = parser.iterate_many(json, ondemand::DEFAULT_BATCH_SIZE,
+                                 simdjson::stream_format::comma_delimited).get(stream);
+if (error) { std::cerr << error << std::endl; return; }
+for (auto doc : stream) {
+    std::cout << doc << std::endl;
+}
+// Prints: {"a":1}
+//         {"b":2}
+//         {"c":3}
 ```
-number
-number
-number
-number
-string
-string
-string
-object
-array
+
+Whitespace around the commas is allowed:
+```cpp
+auto json = R"({"a":1} , {"b":2} , {"c":3})"_padded;  // Also works
 ```
 
+Nested commas inside objects and arrays are preserved:
+```cpp
+auto json = R"({"arr":[1,2,3]},{"obj":{"x":1,"y":2}})"_padded;
+// Correctly parses as 2 documents, not 6
+```
+
+Mixed document types are supported:
+```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;
+auto error = parser.iterate_many(json, ondemand::DEFAULT_BATCH_SIZE,
+                                 simdjson::stream_format::comma_delimited).get(doc_stream);
+if (error) { std::cerr << error << std::endl; return; }
+for (auto doc : doc_stream) {
+    std::cout << doc.type() << std::endl;
+}
+// Prints: number number number number string string string object array
+```
+
+Extra top-level separators are tolerated for compatibility with the legacy
+`allow_comma_separated` behavior. For example, leading commas, trailing commas,
+and repeated commas are treated as empty separators rather than documents.
+
+### Legacy `allow_comma_separated` parameter (deprecated)
+
+The `allow_comma_separated` boolean parameter is deprecated. When set to `true`, it now internally maps to `stream_format::comma_delimited`.
+
+The old single-batch limitation no longer applies - comma-delimited parsing now supports multi-batch processing and threading for optimal performance on large files.
+
+JSON Text Sequences (RFC 7464)
+------------------------------
+
+[RFC 7464](https://tools.ietf.org/html/rfc7464) defines a format for streaming JSON values using ASCII Record Separator (RS, 0x1E) as a delimiter. Each JSON text is preceded by RS and optionally followed by ASCII Line Feed (LF, 0x0A).
+
+Example input:
+```
+<RS>{"name":"doc1"}<LF>
+<RS>{"name":"doc2"}<LF>
+<RS>{"name":"doc3"}<LF>
+```
+
+To parse JSON text sequences, use the `stream_format::json_sequence` parameter:
+
+```cpp
+// Build input with RS (0x1E) and LF (0x0A) delimiters
+std::string input_str;
+input_str += '\x1e'; input_str += "{\"a\":1}"; input_str += '\x0a';
+input_str += '\x1e'; input_str += "{\"b\":2}"; input_str += '\x0a';
+input_str += '\x1e'; input_str += "{\"c\":3}"; input_str += '\x0a';
+simdjson::padded_string input(input_str);
+
+ondemand::parser parser;
+ondemand::document_stream stream;
+auto error = parser.iterate_many(input, ondemand::DEFAULT_BATCH_SIZE,
+                                 simdjson::stream_format::json_sequence).get(stream);
+if (error) { std::cerr << error << std::endl; return; }
+for (auto doc : stream) {
+    std::cout << doc << std::endl;
+}
+```
+
+The `stream_format` enum has the following values:
+- `stream_format::whitespace_delimited` (default): Standard NDJSON/JSON Lines format
+- `stream_format::json_sequence`: RFC 7464 format with RS delimiters
+- `stream_format::comma_delimited`: Comma-separated JSON documents
+- `stream_format::comma_delimited_array`: A single JSON array whose elements are iterated as comma-delimited documents (see below)
+
+The trailing LF after each JSON text is optional but recommended by the RFC for robustness.
+
+JSON Array As A Document Stream
+-------------------------------
+
+Sometimes an input is a single, well-formed JSON array — `[{"a":1},{"b":2},{"c":3}]` — but you want to iterate its elements one at a time without materializing the whole array. Use `stream_format::comma_delimited_array`:
+
+```cpp
+auto json = R"([{"a":1},{"b":2},{"c":3}])"_padded;
+ondemand::parser parser;
+ondemand::document_stream stream;
+auto error = parser.iterate_many(json, ondemand::DEFAULT_BATCH_SIZE,
+                                 simdjson::stream_format::comma_delimited_array).get(stream);
+if (error) { std::cerr << error << std::endl; return; }
+for (auto doc : stream) {
+    std::cout << doc << std::endl;
+}
+// Prints: {"a":1}
+//         {"b":2}
+//         {"c":3}
+```
+
+The parser strips the outer `[` and `]` plus any surrounding JSON whitespace (space, tab, LF, CR) and then behaves exactly like `stream_format::comma_delimited` over the remaining bytes. All comma-delimited features are inherited: multi-batch processing, threading, mixed scalar types, and nested commas preserved inside inner objects and arrays.
+
+```cpp
+// All of these work:
+auto a = R"([1, "x", true, null, {"k":"v"}, [1,2]])"_padded;  // mixed scalars
+auto b = R"(  [ 1, 2, 3 ] )"_padded;                          // whitespace
+auto c = R"([])"_padded;                                      // empty array → 0 docs
+```
+
+If the input is not a well-formed outer array (missing `[`, missing `]`, or empty / all-whitespace), `iterate_many` returns `TAPE_ERROR`. Content **inside** the array is not validated up front — individual document parse errors surface when you iterate, just like `comma_delimited`.
+
+Positions reported via `current_index()` are relative to the **stripped** buffer (the bytes between `[` and `]`), not the original input, for consistency with the existing BOM-stripping behavior.
+
 
 C++20 features
 --------------------
@@ -404,3 +578,161 @@ Otherwise you may use this longer version for explicit handling of errors:
     cars.push_back(c);
   }
 ```
+
+**Performance tip**: You will get better performance if you order the attributes (make, model)
+in the order they appear in the JSON document.
+
+C++26 features (static reflection)
+-----------------------------------
+
+If you have a C++26 compatible compiler with [P2996](https://wg21.link/P2996)
+static reflection support, you can compile the simdjson library with the
+`SIMDJSON_STATIC_REFLECTION` macro set to `1`. When this is the case, simdjson
+can deserialize a stream of JSON documents directly into your own structures
+**without** writing any `tag_invoke` function. The library inspects the
+non-static public members of your type at compile time and produces the
+parsing code automatically.
+
+```cpp
+#define SIMDJSON_STATIC_REFLECTION 1
+#include "simdjson.h"
+```
+
+Consider the same `Car` structure used in the C++20 example, but **without**
+any `tag_invoke` glue:
+
+```cpp
+struct Car {
+  std::string make;
+  std::string model;
+  int year;
+  std::vector<double> tire_pressure;
+};
+```
+
+With C++26 static reflection enabled, you can iterate a stream of cars and
+push them into a `std::vector<Car>` directly:
+
+```cpp
+auto json = R"( { "make": "Toyota", "model": "Camry",  "year": 2018,
+                  "tire_pressure": [ 40.1, 39.9 ] }
+                { "make": "Kia",    "model": "Soul",   "year": 2012,
+                  "tire_pressure": [ 30.1, 31.0 ] }
+                { "make": "Toyota", "model": "Tercel", "year": 1999,
+                  "tire_pressure": [ 29.8, 30.0 ] } )"_padded;
+ondemand::parser parser;
+ondemand::document_stream stream;
+auto error = parser.iterate_many(json).get(stream);
+if (error) { /* handle error */ }
+std::vector<Car> cars;
+for (auto doc : stream) {
+  Car c;
+  if ((error = doc.get<Car>().get(c))) { /* handle error */ }
+  cars.push_back(c);
+}
+```
+
+This works for every `stream_format` value supported by `iterate_many`. The
+following examples each parse the same three cars, but laid out using a
+different streaming convention.
+
+### Whitespace-delimited (default, NDJSON / JSON Lines)
+
+```cpp
+auto json = R"( { "make": "Toyota", "model": "Camry",  "year": 2018,
+                  "tire_pressure": [ 40.1, 39.9 ] }
+                { "make": "Kia",    "model": "Soul",   "year": 2012,
+                  "tire_pressure": [ 30.1, 31.0 ] }
+                { "make": "Toyota", "model": "Tercel", "year": 1999,
+                  "tire_pressure": [ 29.8, 30.0 ] } )"_padded;
+ondemand::parser parser;
+ondemand::document_stream stream;
+auto error = parser.iterate_many(json, ondemand::DEFAULT_BATCH_SIZE,
+                                 simdjson::stream_format::whitespace_delimited).get(stream);
+if (error) { /* handle error */ }
+std::vector<Car> cars;
+for (auto doc : stream) {
+  cars.push_back((Car)doc); // throws on error
+}
+```
+
+### Comma-delimited documents
+
+```cpp
+auto json = R"( { "make": "Toyota", "model": "Camry",  "year": 2018,
+                  "tire_pressure": [ 40.1, 39.9 ] },
+                { "make": "Kia",    "model": "Soul",   "year": 2012,
+                  "tire_pressure": [ 30.1, 31.0 ] },
+                { "make": "Toyota", "model": "Tercel", "year": 1999,
+                  "tire_pressure": [ 29.8, 30.0 ] } )"_padded;
+ondemand::parser parser;
+ondemand::document_stream stream;
+auto error = parser.iterate_many(json, ondemand::DEFAULT_BATCH_SIZE,
+                                 simdjson::stream_format::comma_delimited).get(stream);
+if (error) { /* handle error */ }
+std::vector<Car> cars;
+for (auto doc : stream) {
+  Car c;
+  if ((error = doc.get<Car>().get(c))) { /* handle error */ }
+  cars.push_back(c);
+}
+```
+
+### A single JSON array as a stream of documents
+
+When the input is a single JSON array, you can stream its elements one at a
+time without materializing the entire array as a `std::vector` upfront:
+
+```cpp
+auto json = R"( [ { "make": "Toyota", "model": "Camry",  "year": 2018,
+                    "tire_pressure": [ 40.1, 39.9 ] },
+                  { "make": "Kia",    "model": "Soul",   "year": 2012,
+                    "tire_pressure": [ 30.1, 31.0 ] },
+                  { "make": "Toyota", "model": "Tercel", "year": 1999,
+                    "tire_pressure": [ 29.8, 30.0 ] } ] )"_padded;
+ondemand::parser parser;
+ondemand::document_stream stream;
+auto error = parser.iterate_many(json, ondemand::DEFAULT_BATCH_SIZE,
+                                 simdjson::stream_format::comma_delimited_array).get(stream);
+if (error) { /* handle error */ }
+std::vector<Car> cars;
+for (auto doc : stream) {
+  Car c;
+  if ((error = doc.get<Car>().get(c))) { /* handle error */ }
+  cars.push_back(c);
+}
+```
+
+### JSON Text Sequences (RFC 7464)
+
+```cpp
+// Build input with RS (0x1E) and LF (0x0A) delimiters
+std::string input_str;
+auto append = [&](std::string_view doc) {
+  input_str += '\x1e'; input_str += doc; input_str += '\x0a';
+};
+append(R"({ "make": "Toyota", "model": "Camry",  "year": 2018, "tire_pressure": [ 40.1, 39.9 ] })");
+append(R"({ "make": "Kia",    "model": "Soul",   "year": 2012, "tire_pressure": [ 30.1, 31.0 ] })");
+append(R"({ "make": "Toyota", "model": "Tercel", "year": 1999, "tire_pressure": [ 29.8, 30.0 ] })");
+simdjson::padded_string input(input_str);
+
+ondemand::parser parser;
+ondemand::document_stream stream;
+auto error = parser.iterate_many(input, ondemand::DEFAULT_BATCH_SIZE,
+                                 simdjson::stream_format::json_sequence).get(stream);
+if (error) { /* handle error */ }
+std::vector<Car> cars;
+for (auto doc : stream) {
+  Car c;
+  if ((error = doc.get<Car>().get(c))) { /* handle error */ }
+  cars.push_back(c);
+}
+```
+
+In every case, the user-defined type (`Car` here) does not need a hand-written
+`tag_invoke` overload: the library generates the deserialization code from the
+type's public data members at compile time.
+
+
+**Performance tip**: You will get better performance if you order the attributes (make, model)
+in the order they appear in the JSON document.

doc/parse_many.md

@@ -18,6 +18,7 @@ Contents
 - [How it works](#how-it-works)
 - [Support](#support)
 - [API](#api)
+- [Streaming directly from a memory-mapped file](#streaming-directly-from-a-memory-mapped-file)
 - [Use cases](#use-cases)
 - [Tracking your position](#tracking-your-position)
 - [Incomplete streams](#incomplete-streams)
@@ -132,7 +133,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 simdjson!
+- [Record separator-delimited JSON (RFC 7464)](https://tools.ietf.org/html/rfc7464)
 - [More on Wikipedia...](https://en.wikipedia.org/wiki/JSON_streaming)
 
 API
@@ -217,6 +218,86 @@ got full document at 29
 ```
 
 
+
+Streaming directly from a memory-mapped file
+--------------------------------------------
+
+When your input is a large NDJSON / JSON-lines file on disk, the most
+efficient way to feed `parse_many` is to use `simdjson::padded_memory_map`.
+It returns a `padded_string_view` with the right amount of trailing padding,
+so you can pass it directly to `parse_many` without copying the file content
+into your own buffer first.
+
+`padded_memory_map` is available on POSIX systems (Linux, macOS, BSD, ...) by
+default. On Windows it is an **opt-in** feature with the following
+requirements:
+
+1. Build simdjson with `-DSIMDJSON_ENABLE_MEMORY_FILE_MAPPING_ON_WINDOWS=ON`, or — if
+   you consume simdjson as a pre-built library — define
+   `SIMDJSON_ENABLE_MEMORY_FILE_MAPPING_ON_WINDOWS=1`, raise `NTDDI_VERSION` to at
+   least `NTDDI_WIN10_RS4` (`0x0A000005`, Windows 10 version 1803), and
+   add `onecore.lib` to your link line yourself. The Windows
+   implementation uses the modern memory APIs `CreateFileMapping2` /
+   `MapViewOfFile3`, which are available starting with that version of
+   Windows and are exported by `onecore.lib`.
+2. `#include <windows.h>` before `#include "simdjson.h"` in every
+   translation unit where you want to use `padded_memory_map`. simdjson
+   deliberately does not pull in `<windows.h>` itself, so the class is
+   only declared when the Win32 types are already visible.
+
+If either requirement is not met on Windows, the `padded_memory_map` class is
+not declared at all and any code that references it fails to compile with an
+"unknown identifier" error. The availability of the class can be tested with
+the macro `SIMDJSON_HAS_PADDED_MEMORY_MAP`.
+
+On POSIX, `padded_memory_map` uses `mmap` to map the file directly into
+memory with zero copies. On Windows (when enabled), it uses
+`CreateFileMapping2` + `MapViewOfFile3` for true zero-copy mapping
+whenever the file does not end within `SIMDJSON_PADDING` bytes of a page
+boundary; for those rare cases, it transparently falls back to reading
+the file into a heap-allocated padded buffer so that the returned view
+always has `SIMDJSON_PADDING` accessible zero bytes after the file content.
+
+```cpp
+#ifdef _WIN32
+#include <windows.h> // Must come BEFORE <simdjson.h> on Windows
+#endif
+#include "simdjson.h"
+
+// ...
+
+simdjson::padded_memory_map map("huge_stream.ndjson");
+if (!map.is_valid()) { /* file missing, unreadable, too large, ... */ return; }
+
+simdjson::dom::parser parser;
+simdjson::dom::document_stream stream;
+auto error = parser.parse_many(map.view()).get(stream);
+if (error) { std::cerr << error << std::endl; return; }
+
+for (auto doc : stream) {
+  // process each JSON document in the stream
+  std::cout << doc << std::endl;
+}
+```
+
+Important lifetime rule: the `padded_string_view` returned by `map.view()` is
+only valid while the `padded_memory_map` instance is alive, so keep `map`
+alive for as long as you are iterating the stream.
+
+The file must not be modified while the memory map is in use. If you need a
+fully independent copy of the data, use `simdjson::padded_string::load(...)`
+instead.
+
+If you prefer single-document parsing on a memory-mapped file, the same
+pattern applies to `parser.parse(...)`:
+
+```cpp
+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
+simdjson::dom::element doc = parser.parse(view); // parse the JSON
+```
+
 Incomplete streams
 -----------
 
@@ -239,3 +320,115 @@ Consider the following example where a truncated document (`{"key":"intentionall
 
 
 Importantly, you should only call `truncated_bytes()` after iterating through all of the documents since the stream cannot tell whether there are truncated documents at the very end when it may not have accessed that part of the data yet.
+
+JSON Text Sequences (RFC 7464)
+------------------------------
+
+[RFC 7464](https://tools.ietf.org/html/rfc7464) defines a format for streaming JSON values using ASCII Record Separator (RS, 0x1E) as a delimiter. Each JSON text is preceded by RS and optionally followed by ASCII Line Feed (LF, 0x0A).
+
+Example input:
+```
+<RS>{"name":"doc1"}<LF>
+<RS>{"name":"doc2"}<LF>
+<RS>{"name":"doc3"}<LF>
+```
+
+To parse JSON text sequences, use the `stream_format::json_sequence` parameter:
+
+```cpp
+// Build input with RS (0x1E) and LF (0x0A) delimiters
+std::string input_str;
+input_str += '\x1e'; input_str += "{\"a\":1}"; input_str += '\x0a';
+input_str += '\x1e'; input_str += "{\"b\":2}"; input_str += '\x0a';
+input_str += '\x1e'; input_str += "{\"c\":3}"; input_str += '\x0a';
+simdjson::padded_string input(input_str);
+
+simdjson::dom::parser parser;
+simdjson::dom::document_stream stream;
+auto error = parser.parse_many(input, simdjson::dom::DEFAULT_BATCH_SIZE,
+                               simdjson::stream_format::json_sequence).get(stream);
+if (error) { std::cerr << error << std::endl; return; }
+for (auto doc : stream) {
+    std::cout << doc << std::endl;
+}
+```
+
+The `stream_format` enum has the following values:
+- `stream_format::whitespace_delimited` (default): Standard NDJSON/JSON Lines format
+- `stream_format::json_sequence`: RFC 7464 format with RS delimiters
+- `stream_format::comma_delimited`: Comma-separated JSON documents
+- `stream_format::comma_delimited_array`: A single JSON array whose elements are iterated as comma-delimited documents (see below)
+
+The trailing LF after each JSON text is optional but recommended by the RFC for robustness.
+
+Comma-Separated Documents
+-------------------------
+
+Some systems produce JSON documents separated by commas, like `{"a":1},{"b":2},{"c":3}`. This is common when extracting elements from a JSON array or when APIs return comma-separated results.
+
+To parse comma-separated documents, use the `stream_format::comma_delimited` parameter:
+
+```cpp
+auto json = R"({"a":1},{"b":2},{"c":3})"_padded;
+simdjson::dom::parser parser;
+simdjson::dom::document_stream stream;
+auto error = parser.parse_many(json, simdjson::dom::DEFAULT_BATCH_SIZE,
+                               simdjson::stream_format::comma_delimited).get(stream);
+if (error) { std::cerr << error << std::endl; return; }
+for (auto doc : stream) {
+    std::cout << doc << std::endl;
+}
+// Prints: {"a":1}
+//         {"b":2}
+//         {"c":3}
+```
+
+Whitespace around the commas is allowed:
+```cpp
+auto json = R"({"a":1} , {"b":2} , {"c":3})"_padded;  // Also works
+```
+
+Nested commas inside objects and arrays are preserved:
+```cpp
+auto json = R"({"arr":[1,2,3]},{"obj":{"x":1,"y":2}})"_padded;
+// Correctly parses as 2 documents, not 6
+```
+
+Extra top-level separators are tolerated for compatibility with the legacy
+On-Demand comma-separated mode. Leading commas, trailing commas, and repeated
+commas are treated as empty separators rather than documents.
+
+Unlike the legacy `allow_comma_separated` parameter, `stream_format::comma_delimited` supports multi-batch processing and threading for optimal performance on large files.
+
+JSON Array As A Document Stream
+-------------------------------
+
+Sometimes an input is a single, well-formed JSON array — `[{"a":1},{"b":2},{"c":3}]` — but you want to iterate its elements one at a time without materializing the whole array. Use `stream_format::comma_delimited_array`:
+
+```cpp
+auto json = R"([{"a":1},{"b":2},{"c":3}])"_padded;
+simdjson::dom::parser parser;
+simdjson::dom::document_stream stream;
+auto error = parser.parse_many(json, simdjson::dom::DEFAULT_BATCH_SIZE,
+                               simdjson::stream_format::comma_delimited_array).get(stream);
+if (error) { std::cerr << error << std::endl; return; }
+for (auto doc : stream) {
+    std::cout << doc << std::endl;
+}
+// Prints: {"a":1}
+//         {"b":2}
+//         {"c":3}
+```
+
+The parser strips the outer `[` and `]` plus any surrounding JSON whitespace (space, tab, LF, CR) and then behaves exactly like `stream_format::comma_delimited` over the remaining bytes. All comma-delimited features are inherited: multi-batch processing, threading, mixed scalar types, and nested commas preserved inside inner objects and arrays.
+
+```cpp
+// All of these work:
+auto a = R"([1, "x", true, null, {"k":"v"}, [1,2]])"_padded;  // mixed scalars
+auto b = R"(  [ 1, 2, 3 ] )"_padded;                          // whitespace
+auto c = R"([])"_padded;                                      // empty array → 0 docs
+```
+
+If the input is not a well-formed outer array (missing `[`, missing `]`, or empty / all-whitespace), `parse_many` returns `TAPE_ERROR`. Content **inside** the array is not validated up front — individual document parse errors surface when you iterate, just like `comma_delimited`.
+
+Positions reported via `current_index()` are relative to the **stripped** buffer (the bytes between `[` and `]`), not the original input, for consistency with the existing BOM-stripping behavior.

doc/performance.md

@@ -204,9 +204,31 @@ but can be significantly larger. E.g., Apple systems favour pages spanning 16 ki
 
 In effect, it means that you can almost always read a few bytes beyond your current buffer---without
 allocating extra memory. However, tools such as valgrind or memory sanitizers will flag such behavior as unsafe.
-Nevertheless, you can still make sure of this capability in your code if you are an expert
-programmer and you are willing to silence sanitizer warnings. The following code provides
-a portable example.
+You can still make sure of this capability in your code if you are an expert
+programmer and you are willing to silence sanitizer warnings.
+
+If you are building simdjson with C++17 or better, you can use `simdjson::padded_input`.
+The `padded_input` struct automatically manages padding for you. It can be constructed from a `std::string_view`, a C-style string with length, or a `std::string`. For `std::string`, it takes into account the reserved capacity when determining if sufficient padding exists. If the input already has sufficient padding (up to the end of the memory page), it creates a view without copying. Otherwise, it copies the data into a `padded_string` with proper padding.
+
+Example usage:
+
+```cpp
+std::string_view json = get_json_data();
+simdjson::padded_input input(json);  // Automatically pads if needed
+auto result = parser.parse(input);
+
+// Also works with std::string, considering capacity
+std::string json_str = get_json_string();
+json_str.reserve(json_str.size() + 100);  // Reserve extra space
+simdjson::padded_input input2(json_str);  // May avoid copying if capacity is sufficient
+auto result2 = parser.parse(input2);
+```
+
+This simplifies padding management compared to manually checking and allocating.
+
+
+More generally, the following code provides a portable example.
+
 
 
 The conditional compilation checks for the `_MSC_VER` macro (indicating Microsoft Visual Studio)
@@ -250,7 +272,7 @@ long page_size() {
 }
 
 // Returns true if the buffer + len + simdjson::SIMDJSON_PADDING crosses the
-// page boundary.
+// page boundary. Assumes len != 0.
 bool need_allocation(const char *buf, size_t len) {
   return ((reinterpret_cast<uintptr_t>(buf + len - 1) % page_size())
     + simdjson::SIMDJSON_PADDING >= static_cast<uintptr_t>(page_size()));
@@ -297,4 +319,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;
+}
 ```

doc/tape.md

@@ -93,6 +93,14 @@ Float values are represented as two 64-bit tape elements:
 
 Performance consideration: We store numbers of the main tape because we believe that locality of reference is helpful for performance.
 
+## Big Integers
+
+When a JSON integer exceeds the 64-bit range (both signed and unsigned), it is classified as a big integer. By default, parsing returns `BIGINT_ERROR`. When `parser.number_as_string(true)` is set, the raw digits are stored on the string tape using the same format as strings (4-byte little-endian length prefix, followed by the UTF-8 digit bytes, followed by a null terminator).
+
+A big integer is represented on the main tape as the 64-bit tape element `('Z' << 56) + x` where the payload `x` is the location on the string tape of the null-terminated digit string.
+
+For example, the JSON value `99999999999999999999` would be stored as the string `"99999999999999999999"` on the string tape, with a `'Z'` tag on the main tape. Negative big integers include the leading minus sign.
+
 ## Root node
 
 Each JSON document will have two special 64-bit tape elements representing a root node, one at the beginning and one at the end.

fuzz/fuzz_dump.cpp

@@ -54,6 +54,9 @@ static void print_json(std::ostream& os, simdjson::dom::element element) noexcep
   case simdjson::dom::element_type::NULL_VALUE:
     os << "null" << endl;
     break;
+  case simdjson::dom::element_type::BIGINT:
+    os << element.get_bigint().value_unsafe() << endl;
+    break;
   }
 }
 extern "C" int LLVMFuzzerTestOneInput(const uint8_t *Data, size_t Size) {

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,6 +52,7 @@
 #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"

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/base.h

@@ -21,6 +21,10 @@ SIMDJSON_PUSH_DISABLE_UNUSED_WARNINGS
 
 /** The maximum document size supported by simdjson. */
 constexpr size_t SIMDJSON_MAXSIZE_BYTES = 0xFFFFFFFF;
+/** The maximum depth of nested objects and arrays supported by simdjson.
+ A depth of SIMDJSON_MAXSIZE_BYTES/2 is not reasonable and would be
+ adversarial, but it serves as an upper bound for validation purposes. */
+constexpr size_t SIMDJSON_MAX_DEPTH = SIMDJSON_MAXSIZE_BYTES/2;
 
 /**
  * The amount of padding needed in a buffer to parse JSON.
@@ -46,6 +50,21 @@ struct padded_string;
 class padded_string_view;
 enum class stage1_mode;
 
+/**
+ * Stream format for parse_many/iterate_many.
+ */
+enum class stream_format {
+  whitespace_delimited, ///< Whitespace-delimited JSON documents (default, includes NDJSON/JSONL)
+  json_sequence,        ///< RFC 7464 JSON text sequences (RS-delimited)
+  comma_delimited,      ///< Comma-separated JSON documents (e.g., `{...},{...},{...}`)
+  comma_delimited_array ///< A single JSON array whose elements are iterated as
+                        ///< comma-separated documents (e.g., `[{...},{...},{...}]`).
+                        ///< The parser strips the outer `[` / `]` plus any
+                        ///< surrounding JSON whitespace (space, tab, LF, CR)
+                        ///< and then behaves like `comma_delimited` over the
+                        ///< remaining bytes.
+};
+
 namespace internal {
 
 template<typename T>

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

@@ -30,6 +30,10 @@ double from_chars(const char *first, const char* end) noexcept;
 #endif
 #endif
 
+#ifndef SIMDJSON_ENABLE_NAN_INF
+#define SIMDJSON_ENABLE_NAN_INF 0
+#endif
+
 } // namespace simdjson
 
 #if defined(__GNUC__)
@@ -45,9 +49,6 @@ double from_chars(const char *first, const char* end) noexcept;
 
 // Align to N-byte boundary
 #define SIMDJSON_ROUNDUP_N(a, n) (((a) + ((n)-1)) & ~((n)-1))
-#define SIMDJSON_ROUNDDOWN_N(a, n) ((a) & ~((n)-1))
-
-#define SIMDJSON_ISALIGNED_N(ptr, n) (((uintptr_t)(ptr) & ((n)-1)) == 0)
 
 #if SIMDJSON_REGULAR_VISUAL_STUDIO
   // We could use [[deprecated]] but it requires C++14
@@ -55,6 +56,7 @@ double from_chars(const char *first, const char* end) noexcept;
 
   #define simdjson_really_inline __forceinline
   #define simdjson_never_inline __declspec(noinline)
+  #define simdjson_really_flatten [[msvc::flatten]]
 
   #define simdjson_unused
   #define simdjson_warn_unused
@@ -95,6 +97,7 @@ double from_chars(const char *first, const char* end) noexcept;
 
   #define simdjson_really_inline inline __attribute__((always_inline))
   #define simdjson_never_inline inline __attribute__((noinline))
+  #define simdjson_really_flatten [[gnu::flatten]]
 
   #define simdjson_unused __attribute__((unused))
   #define simdjson_warn_unused __attribute__((warn_unused_result))
@@ -171,6 +174,15 @@ double from_chars(const char *first, const char* end) noexcept;
   #define simdjson_inline simdjson_really_inline
 #endif
 
+#if defined(simdjson_flatten)
+  // Prefer the user's definition of simdjson_flatten; don't define it ourselves.
+#elif (defined(__GNUC__) && !defined(__OPTIMIZE__)) || (defined(_DEBUG) && _MSC_VER )
+  // Flattening can lead to significant code bloat and high compile times. Don't use it for unoptimized builds.
+  #define simdjson_flatten
+#else
+  #define simdjson_flatten simdjson_really_flatten
+#endif
+
 #if SIMDJSON_VISUAL_STUDIO
     /**
      * Windows users need to do some extra work when building
@@ -289,7 +301,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-inl.h

@@ -266,6 +266,12 @@ consteval std::pair<double, size_t> parse_double(const char *src,
 }
 } // namespace number_parsing
 
+consteval auto make_data_member_options(auto&& name_str) {
+  std::meta::data_member_options options{};
+  options.name = std::forward<decltype(name_str)>(name_str);
+  return options;
+}
+
 // JSON string may contain embedded nulls, and C++26 reflection does not yet
 // support std::string_view as a data member type. As a workaround, we define
 // a custom type that holds a const char* and a size.
@@ -320,7 +326,8 @@ using class_type = type_builder<meta_info...>::constructed_type;
 /**
  * @brief Variable template for constructing instances with values
  */
-template <typename T, auto... Vs> constexpr auto construct_from = T{Vs...};
+template <typename T, auto... Vs> constexpr T construct_from = T{Vs...};
+
 
 // in JSON, there are only a few whitespace characters that are allowed
 // outside of objects, arrays, strings, and numbers.
@@ -410,7 +417,7 @@ parse_number(std::string_view json,
         std::from_chars(json.data(), json.data() + json.size(), int_value);
     if (res.ec == std::errc()) {
       out = int_value;
-      if ((res.ptr - json.data()) != scope) {
+      if (static_cast<std::size_t>(res.ptr - json.data()) != scope) {
         simdjson_consteval_error(
             "Internal error: cannot agree on the character range of the float");
       }
@@ -424,7 +431,7 @@ parse_number(std::string_view json,
         std::from_chars(json.data(), json.data() + json.size(), uint_value);
     if (res.ec == std::errc()) {
       out = uint_value;
-      if ((res.ptr - json.data()) != scope) {
+      if (static_cast<std::size_t>(res.ptr - json.data()) != scope) {
         simdjson_consteval_error(
             "Internal error: cannot agree on the character range of the float");
       }
@@ -533,7 +540,7 @@ parse_string(std::string_view json) {
       // present, we have an error (isolated high surrogate), which we
       // tolerate by substituting the substitution_code_point.
       if (end - cursor < 6 || *cursor != '\\' ||
-          *(cursor + 1) != 'u' > 0xFFFF) {
+          *(cursor + 1) != 'u') {
         code_point = substitution_code_point;
       } else {       // we have \u following the high surrogate
         cursor += 2; // skip \u
@@ -887,10 +894,19 @@ parse_json_array_impl(const std::string_view json) {
   std::size_t count = values.size() - 1;
   // We assume all elements have the same type as the first element.
   // However, if the array is heterogeneous, we should use std::variant.
+  auto elem_type = std::meta::type_of(values[1]);
+  // String literals reflected via reflect_constant_string have type const
+  // char[N], but when passed as template auto parameters they decay to
+  // const char*.  Use const char* as the element type so that
+  // construct_from can aggregate-initialize the array.
+  if (std::meta::is_array_type(elem_type) &&
+      std::meta::remove_all_extents(elem_type) == ^^const char) {
+    elem_type = ^^const char *;
+  }
   auto array_type = std::meta::substitute(
       ^^std::array,
       {
-          std::meta::type_of(values[1]), std::meta::reflect_constant(count)});
+          elem_type, std::meta::reflect_constant(count)});
 
   // Create array instance with values
   values[0] = array_type;
@@ -957,8 +973,7 @@ parse_json_object_impl(std::string_view json) {
         simdjson_consteval_error("Expected '}'");
       }
       cursor += object_size;
-      auto dms = std::meta::data_member_spec(std::meta::type_of(parsed),
-                                             {.name = field_name});
+      auto dms = std::meta::data_member_spec(std::meta::type_of(parsed), make_data_member_options(field_name));
       members.push_back(std::meta::reflect_constant(dms));
       values.push_back(parsed);
 
@@ -967,8 +982,7 @@ parse_json_object_impl(std::string_view json) {
     case '[': {
       std::string_view value(cursor, end);
       auto [parsed, array_size] = parse_json_array_impl(value);
-      auto dms = std::meta::data_member_spec(std::meta::type_of(parsed),
-                                             {.name = field_name});
+      auto dms = std::meta::data_member_spec(std::meta::type_of(parsed), make_data_member_options(field_name));
       members.push_back(std::meta::reflect_constant(dms));
       values.push_back(parsed);
       if (*(cursor + array_size - 1) != ']') {
@@ -989,8 +1003,7 @@ parse_json_object_impl(std::string_view json) {
         }
       }
       auto dms =
-          std::meta::data_member_spec(^^const char *, {
-                                                          .name = field_name});
+          std::meta::data_member_spec(^^const char *, make_data_member_options(field_name));
       members.push_back(std::meta::reflect_constant(dms));
       values.push_back(std::meta::reflect_constant_string(value));
       break;
@@ -1001,8 +1014,7 @@ parse_json_object_impl(std::string_view json) {
       }
       cursor += 4;
 
-      auto dms = std::meta::data_member_spec(^^bool, {
-                                                         .name = field_name});
+      auto dms = std::meta::data_member_spec(^^bool, make_data_member_options(field_name));
       members.push_back(std::meta::reflect_constant(dms));
       values.push_back(std::meta::reflect_constant(true));
       break;
@@ -1013,8 +1025,7 @@ parse_json_object_impl(std::string_view json) {
       }
       cursor += 5;
 
-      auto dms = std::meta::data_member_spec(^^bool, {
-                                                         .name = field_name});
+      auto dms = std::meta::data_member_spec(^^bool, make_data_member_options(field_name));
       members.push_back(std::meta::reflect_constant(dms));
       values.push_back(std::meta::reflect_constant(false));
       break;
@@ -1025,9 +1036,7 @@ parse_json_object_impl(std::string_view json) {
       }
       cursor += 4;
 
-      auto dms = std::meta::data_member_spec(^^std::nullptr_t,
-                                             {
-                                                 .name = field_name});
+      auto dms = std::meta::data_member_spec(^^std::nullptr_t, make_data_member_options(field_name));
       members.push_back(std::meta::reflect_constant(dms));
       values.push_back(std::meta::reflect_constant(nullptr));
       break;
@@ -1051,22 +1060,19 @@ parse_json_object_impl(std::string_view json) {
       if (std::holds_alternative<int64_t>(out)) {
         int64_t int_value = std::get<int64_t>(out);
         auto dms =
-            std::meta::data_member_spec(^^int64_t, {
-                                                       .name = field_name});
+            std::meta::data_member_spec(^^int64_t, make_data_member_options(field_name));
         members.push_back(std::meta::reflect_constant(dms));
         values.push_back(std::meta::reflect_constant(int_value));
       } else if (std::holds_alternative<uint64_t>(out)) {
         uint64_t uint_value = std::get<uint64_t>(out);
         auto dms =
-            std::meta::data_member_spec(^^uint64_t, {
-                                                        .name = field_name});
+            std::meta::data_member_spec(^^uint64_t, make_data_member_options(field_name));
         members.push_back(std::meta::reflect_constant(dms));
         values.push_back(std::meta::reflect_constant(uint_value));
       } else {
         double float_value = std::get<double>(out);
         auto dms =
-            std::meta::data_member_spec(^^double, {
-                                                      .name = field_name});
+            std::meta::data_member_spec(^^double, make_data_member_options(field_name));
         members.push_back(std::meta::reflect_constant(dms));
         values.push_back(std::meta::reflect_constant(float_value));
       }
@@ -1111,16 +1117,11 @@ template <constevalutil::fixed_string json_str> consteval auto parse_json() {
                 "Only JSON objects and arrays are supported at the top level, this "
                 "limitation will be lifted in the future.");*/
 
-  constexpr auto result = json.front() == '['
-                              ? parse_json_array_impl(json)
-                              : parse_json_object_impl(json);
-  return [: result.first :];
-  /*
-  if(json.front() == '[') {
-      return [:parse_json_array_impl(json).first:];
-  } else if(json.front() == '{') {
-   //   return [:parse_json_object_impl(json).first:];
-  }*/
+  if constexpr (json.front() == '[') {
+    return [: parse_json_array_impl(json).first :];
+  } else {
+    return [: parse_json_object_impl(json).first :];
+  }
 }
 
 } // namespace compile_time

include/simdjson/compile_time_json.h

@@ -63,13 +63,16 @@ namespace compile_time {
 template <constevalutil::fixed_string json_str> consteval auto parse_json();
 
 } // namespace compile_time
-} // namespace simdjson
 
+inline namespace literals {
 
 template <simdjson::constevalutil::fixed_string str>
 consteval auto operator ""_json() {
   return simdjson::compile_time::parse_json<str>();
 }
 
+} // namespace literals
+} // namespace simdjson
+
 #endif // SIMDJSON_STATIC_REFLECTION
 #endif // SIMDJSON_GENERIC_COMPILE_TIME_JSON_H