Merge branch 'master' into francisco/toy_example

Introducing simplified api with from/to adapters (thanks to @the-moisrex for driving this) and fixing all the CI errors.

.clangd

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

.github/ISSUE_TEMPLATE/config.yml

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

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

@@ -18,7 +18,7 @@ We do not make changes to simdjson without clearly identifiable benefits, which
 
 Is your issue:
 
-1. A bug report? If so, please point at a reproducible test. Indicate whether you are willing or able to provide a bug fix as a pull request.
+1. A bug report? If so, please point at a reproducible test. Indicate whether you are willing or able to provide a bug fix as a pull request. As a matter of policy, we do not consider a compiler warning to be a bug.
 
 2. A build issue? If so, provide all possible details regarding your system configuration. If we cannot reproduce your issue, we cannot fix it.
 

.github/workflows/aarch64.yml

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

.github/workflows/cifuzz.yml

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

.github/workflows/documentation.yml

@@ -1,9 +1,8 @@
 name: Doxygen GitHub Pages
 
 on:
-  push:
-    branches:
-      - master
+  release:
+    types: [created]
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 

.github/workflows/emscripten.yml

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

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

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

.github/workflows/fuzzers.yml

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

.github/workflows/msys2-clang.yml

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

.github/workflows/msys2.yml

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

.github/workflows/ppc64.yml

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

.github/workflows/riscv64.yml

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

.github/workflows/s390x.yml

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

.github/workflows/ubuntu20-gcc8.yml

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

.github/workflows/ubuntu20.yml

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

.github/workflows/ubuntu22-gcc13.yml

@@ -1,23 +0,0 @@
-name: Ubuntu 22.04 CI (GCC 13)
-
-on: [push, pull_request]
-
-jobs:
-  ubuntu-build:
-    if: >-
-      ! contains(toJSON(github.event.commits.*.message), '[skip ci]') &&
-      ! contains(toJSON(github.event.commits.*.message), '[skip github]')
-    runs-on: ubuntu-22.04
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/cache@v4
-        with:
-          path: dependencies/.cache
-          key: ${{ hashFiles('dependencies/CMakeLists.txt') }}
-      - name: Use cmake
-        run: |
-          mkdir build &&
-          cd build &&
-          CXX=g++-13 cmake -DSIMDJSON_DEVELOPER_MODE=ON ..  &&
-          cmake --build .   &&
-          ctest --output-on-failure -LE explicitonly -j

.github/workflows/ubuntu24-checkperf.yml

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

.github/workflows/ubuntu24-cxx20.yml

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

.github/workflows/ubuntu24-noexcept.yml

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

.github/workflows/ubuntu24-nothread.yml

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

.github/workflows/ubuntu24-sani.yml

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

.github/workflows/ubuntu24.yml

@@ -0,0 +1,25 @@
+name: Ubuntu 24.04 CI
+
+on: [push, pull_request]
+jobs:
+  ubuntu-build:
+    if: >-
+      ! contains(toJSON(github.event.commits.*.message), '[skip ci]') &&
+      ! contains(toJSON(github.event.commits.*.message), '[skip github]')
+    runs-on: ubuntu-24.04
+    strategy:
+      matrix:
+        shared: [ON, OFF]
+        cxx: [g++-13, clang++-16]
+        sanitizer: [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
+        env:
+          CXX: ${{matrix.cxx}}
+      - name: Build
+        run: cmake --build build -j=2
+      - name: Test
+        run: ctest --output-on-failure --test-dir build

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

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

.github/workflows/vs17-ci.yml

@@ -13,10 +13,12 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          - {gen: Visual Studio 17 2022, arch: Win32, shared: ON}
-          - {gen: Visual Studio 17 2022, arch: Win32, shared: OFF}
-          - {gen: Visual Studio 17 2022, arch: x64, shared: ON}
-          - {gen: Visual Studio 17 2022, arch: x64, shared: OFF}
+          - {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}
     steps:
     - name: checkout
       uses: actions/checkout@v4
@@ -24,21 +26,15 @@ jobs:
       run: |
         cmake -G "${{matrix.gen}}" -A ${{matrix.arch}} -DSIMDJSON_DEVELOPER_MODE=ON -DSIMDJSON_COMPETITION=OFF -DBUILD_SHARED_LIBS=${{matrix.shared}} -B build
     - name: Build Debug
-      run: cmake --build build --config Debug --verbose
-    - name: Build Release
-      run: cmake --build build --config Release --verbose
-    - name: Run Release tests
+      run: cmake --build build --config ${{matrix.build_type}} --verbose
+    - name: Run tests
       run: |
         cd build
-        ctest -C Release  -LE explicitonly  --output-on-failure
-    - name: Run Debug tests
-      run: |
-        cd build
-        ctest -C Debug  -LE explicitonly  --output-on-failure
+        ctest -C ${{matrix.build_type}}  -LE explicitonly  --output-on-failure
     - name: Install
       run: |
-        cmake --install build --config Release
+        cmake --install build --config ${{matrix.build_type}}
     - name: Test Installation
       run: |
         cmake -G "${{matrix.gen}}" -A ${{matrix.arch}}  -B build_install_test tests/installation_tests/find
-        cmake --build build_install_test --config Release
+        cmake --build build_install_test --config ${{matrix.build_type}}

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

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

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

@@ -13,29 +13,25 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          - {gen: Visual Studio 17 2022, arch: x64}
+          - {gen: Visual Studio 17 2022, arch: x64, build_type: Debug}
+          - {gen: Visual Studio 17 2022, arch: x64, build_type: Release}
+          - {gen: Visual Studio 17 2022, arch: x64, build_type: RelWithDebInfo}
     steps:
     - name: checkout
       uses: actions/checkout@v4
     - name: Configure
       run: |
         cmake -G "${{matrix.gen}}" -A ${{matrix.arch}}  -T ClangCL -DSIMDJSON_DEVELOPER_MODE=ON -DSIMDJSON_COMPETITION=OFF -B build
-    - name: Build Debug
-      run: cmake --build build --config Debug --verbose
-    - name: Build Release
-      run: cmake --build build --config Release --verbose
-    - name: Run Release tests
+    - name: Build
+      run: cmake --build build --config ${{matrix.build_type}} --verbose
+    - name: Run tests
       run: |
         cd build
-        ctest -C Release  -LE explicitonly  --output-on-failure
-    - name: Run Debug tests
-      run: |
-        cd build
-        ctest -C Debug  -LE explicitonly  --output-on-failure
+        ctest -C ${{matrix.build_type}}  -LE explicitonly  --output-on-failure
     - name: Install
       run: |
-        cmake --install build --config Release
+        cmake --install build --config ${{matrix.build_type}}
     - name: Test Installation
       run: |
         cmake -G "${{matrix.gen}}" -A ${{matrix.arch}}  -B build_install_test tests/installation_tests/find
-        cmake --build build_install_test --config Release
+        cmake --build build_install_test --config ${{matrix.build_type}}

.gitignore

@@ -38,7 +38,7 @@ cmake-build-release/
 .history/
 
 # Visual Studio artifacts
-/VS/
+/.vs/
 
 # C/C++ build outputs
 .build/
@@ -49,6 +49,27 @@ objs
 
 # C++ ignore from https://github.com/github/gitignore/blob/master/C%2B%2B.gitignore
 
+# CMake build artifacts
+CMakeCache.txt
+CMakeFiles/
+CPackConfig.cmake
+CPackSourceConfig.cmake
+Makefile
+cmake_install.cmake
+simdjson-config*.cmake
+simdjson-props.cmake
+simdjson.pc
+
+# Build directories
+deps/
+examples/build_*/
+examples/*_demo
+examples/*_benchmark
+
+# Temporary files
+examples/CMakeLists_demo.txt
+examples/simple_http.h
+
 # Prerequisites
 *.d
 
@@ -106,4 +127,4 @@ objs
 !.vscode/extensions.json
 
 # clangd
-.cache
+.cache

.vscode/settings.json

@@ -109,6 +109,23 @@
         "numbers": "cpp",
         "semaphore": "cpp",
         "stop_token": "cpp",
-        "cfenv": "cpp"
+        "cfenv": "cpp",
+        "format": "cpp",
+        "xlocmes": "cpp",
+        "xlocmon": "cpp",
+        "xlocnum": "cpp",
+        "xloctime": "cpp",
+        "xutility": "cpp",
+        "coroutine": "cpp",
+        "xfacet": "cpp",
+        "xhash": "cpp",
+        "xiosbase": "cpp",
+        "xlocale": "cpp",
+        "xlocbuf": "cpp",
+        "xlocinfo": "cpp",
+        "xmemory": "cpp",
+        "xstring": "cpp",
+        "xtr1common": "cpp",
+        "xtree": "cpp"
     }
 }

CMakeLists.txt

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

CONTRIBUTING.md

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

Doxyfile

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

HACKING.md

@@ -88,8 +88,8 @@ simdjson's source structure, from the top level, looks like this:
   * simdjson/ondemand.h: the `simdjson::ondemand` namespace. Includes all public ondemand classes.
     * simdjson/builtin.h: the `simdjson::builtin` namespace. Aliased to the most universal implementation available.
     * simdjson/builtin/ondemand.h: the `simdjson::builtin::ondemand` namespace.
-    * simdjson/arm64|fallback|haswell|icelake|ppc64|westmere/ondemand.h: the `simdjson::<implementation>::ondemand` namespace. on demand compiled for the specific implementation.
-    * simdjson/generic/ondemand/*.h: individual on demand classes, generically written.
+    * simdjson/arm64|fallback|haswell|icelake|ppc64|westmere/ondemand.h: the `simdjson::<implementation>::ondemand` namespace. On-Demand compiled for the specific implementation.
+    * simdjson/generic/ondemand/*.h: individual On-Demand classes, generically written.
       * simdjson/generic/ondemand/dependencies.h: dependencies on common, non-implementation-specific simdjson classes. This will be included before including amalgamated.h.
       * simdjson/generic/ondemand/amalgamated.h: all generic ondemand classes for an implementation.
 * **src:** The source files for non-inlined functionality (e.g. the architecture-specific parser
@@ -99,7 +99,7 @@ simdjson's source structure, from the top level, looks like this:
   * *.cpp: other misc. implementations, such as `simdjson::implementation` and the minifier.
   * arm64|fallback|haswell|icelake|ppc64|westmere.cpp: Architecture-specific parser implementations.
     * generic/*.h: `simdjson::<implementation>` namespace. Generic implementation of the parser, particularly the `dom_parser_implementation`.
-    * generic/stage1/*.h: `simdjson::<implementation>::stage1` namespace. Generic implementation of the simd-heavy tokenizer/indexer pass of the simdjson parser. Used for the On Demand interface
+    * generic/stage1/*.h: `simdjson::<implementation>::stage1` namespace. Generic implementation of the simd-heavy tokenizer/indexer pass of the simdjson parser. Used for the On-Demand interface
     * generic/stage2/*.h: `simdjson::<implementation>::stage2` namespace. Generic implementation of the tape creator, which consumes the index from stage 1 and actually parses numbers and string and such. Used for the DOM interface.
 
 Other important files and directories:

LICENSE

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

LICENSE-MIT

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

README.md

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

benchmark/CMakeLists.txt

@@ -4,6 +4,9 @@ add_subdirectory(dom)
 include_directories( . linux )
 link_libraries(simdjson-windows-headers test-data)
 link_libraries(simdjson)
+if(SIMDJSON_STATIC_REFLECTION)
+  add_compile_definitions(SIMDJSON_STATIC_REFLECTION=1)
+endif(SIMDJSON_STATIC_REFLECTION)
 
 add_executable(benchfeatures benchfeatures.cpp)
 add_executable(get_corpus_benchmark get_corpus_benchmark.cpp)
@@ -32,3 +35,6 @@ if (TARGET benchmark::benchmark)
   endif()
 endif()
 
+if(SIMDJSON_STATIC_REFLECTION)
+  add_subdirectory(static_reflect)
+endif(SIMDJSON_STATIC_REFLECTION)

benchmark/benchmark_reflection_usage_compilation.sh

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

benchmark/event_counter.h

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

benchmark/find_tweet/nlohmann_json.h

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

benchmark/large_random/simdjson_ondemand.h

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

benchmark/partial_tweets/ondemand.h

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

benchmark/static_reflect/CMakeLists.txt

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

benchmark/static_reflect/benchmark_utils/benchmark_helper.h

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

benchmark/static_reflect/citm_catalog_benchmark/CMakeLists.txt

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

benchmark/static_reflect/citm_catalog_benchmark/benchmark_serialization_citm_catalog.cpp

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

benchmark/static_reflect/citm_catalog_benchmark/citm_catalog_data.h

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

benchmark/static_reflect/citm_catalog_benchmark/nlohmann_citm_catalog_data.h

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

benchmark/static_reflect/serde-benchmark/Cargo.lock

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

benchmark/static_reflect/serde-benchmark/Cargo.toml

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

benchmark/static_reflect/serde-benchmark/README.md

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

benchmark/static_reflect/serde-benchmark/cbindgen.toml

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

benchmark/static_reflect/serde-benchmark/lib.rs

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

benchmark/static_reflect/serde-benchmark/serde_benchmark.h

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

benchmark/static_reflect/twitter_benchmark/CMakeLists.txt

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

benchmark/static_reflect/twitter_benchmark/benchmark_serialization_twitter.cpp

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

benchmark/static_reflect/twitter_benchmark/nlohmann_twitter_data.h

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

benchmark/static_reflect/twitter_benchmark/twitter_data.h

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

benchmark/top_tweet/nlohmann_json.h

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

cmake/CPM.cmake

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

cmake/developer-options.cmake

@@ -2,7 +2,10 @@
 # Flags used by exes and by the simdjson library (project-wide flags)
 #
 add_library(simdjson-internal-flags INTERFACE)
-
+if(NOT DEFINED CMAKE_POSITION_INDEPENDENT_CODE)
+  # We default to ON for all targets, so that we can use the library in shared libraries.
+  set_target_properties(simdjson-internal-flags PROPERTIES POSITION_INDEPENDENT_CODE ON)
+endif(NOT DEFINED CMAKE_POSITION_INDEPENDENT_CODE)
 
 option(SIMDJSON_CHECK_EOF "Check for the end of the input buffer. The setting is unnecessary since we require padding of the inputs. You should expect tests to fail with this option turned on." OFF)
 if(SIMDJSON_CHECK_EOF)
@@ -52,7 +55,6 @@ endif()
 
 option(SIMDJSON_SANITIZE_MEMORY "Sanitize memory" OFF)
 
-
 if(SIMDJSON_SANITIZE_MEMORY)
   message(STATUS "Setting the memory sanitizer.")
   add_compile_options(
@@ -110,8 +112,14 @@ endif()
 
 # We compile tools, tests, etc. with C++ 17. Override yourself if you need on a
 # target.
-set(SIMDJSON_CXX_STANDARD 17 CACHE STRING "the C++ standard to use for simdjson")
-set(CMAKE_CXX_STANDARD ${SIMDJSON_CXX_STANDARD})
+if(SIMDJSON_STATIC_REFLECTION)
+  # This is temporary.
+  set(SIMDJSON_CXX_STANDARD 26 CACHE STRING "the C++ standard to use for simdjson")
+  #set(CMAKE_CXX_STANDARD ${SIMDJSON_CXX_STANDARD})
+else()
+  set(SIMDJSON_CXX_STANDARD 17 CACHE STRING "the C++ standard to use for simdjson")
+  set(CMAKE_CXX_STANDARD ${SIMDJSON_CXX_STANDARD})
+endif()
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
 set(CMAKE_CXX_EXTENSIONS OFF)
 set(CMAKE_THREAD_PREFER_PTHREAD ON)
@@ -158,9 +166,6 @@ We recommend Visual Studio 2019 or better on a 64-bit system.")
     add_compile_options(/Zi)
   endif()
 else()
-  if(NOT WIN32)
-    target_compile_options(simdjson-internal-flags INTERFACE -fPIC)
-  endif()
   target_compile_options(
       simdjson-internal-flags INTERFACE
       -Werror -Wall -Wextra -Weffc++ -Wsign-compare -Wshadow -Wwrite-strings

dependencies/CMakeLists.txt

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

dependencies/import.cmake

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

doc/builder.md

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

doc/dom.md

@@ -1,13 +1,18 @@
 The Document-Object-Model (DOM) front-end
 ==========
 
-An overview of what you need to know to use simdjson, with examples.
+An overview of what you need to know to use simdjson to parse JSON documents with
+our DOM API, with examples. [Our documentation regarding the generation (serialization) of JSON documents is in a
+separate document](https://github.com/simdjson/simdjson/blob/master/doc/builder.md).
 
-* [DOM vs On Demand](#dom-vs-on-demand)
+
+* [DOM vs On-Demand](#dom-vs-on-demand)
 * [The Basics: Loading and Parsing JSON Documents](#the-basics-loading-and-parsing-json-documents-using-the-dom-front-end)
 * [Using the Parsed JSON](#using-the-parsed-json)
 * [C++17 Support](#c17-support)
+* [C++20 Support](#c20-support)
 * [JSON Pointer](#json-pointer)
+* [JSONPath](#jsonpath)
 * [Error Handling](#error-handling)
   * [Error Handling Example](#error-handling-example)
   * [Exceptions](#exceptions)
@@ -18,7 +23,7 @@ An overview of what you need to know to use simdjson, with examples.
 * [Padding and Temporary Copies](#padding-and-temporary-copies)
 * [Performance Tips](#performance-tips)
 
-DOM vs On Demand
+DOM vs On-Demand
 ----------------------------------------------
 
 The simdjson library offers two distinct approaches on how to access a JSON document. We support
@@ -26,6 +31,10 @@ a conventional Document-Object-Model (DOM) front-end. In such a scenario, the JS
 entirely parsed, validated and materialized in memory as the first step. The programmer may
 then access the parsed data using this in-memory model.
 
+On-Demand is a different model where you parse just what you need, directly into your own
+data structure. The On-Demand approach, when well tuned, can provide superior performance.
+[We refer you to the On-Demand documentation for further details](https://github.com/simdjson/simdjson/blob/master/doc/basics.md).
+
 The Basics: Loading and Parsing JSON Documents using the DOM front-end
 ----------------------------------------------
 
@@ -59,6 +68,26 @@ std::string data = "my data";
 simdjson::padded_string my_padded_data(data); // copies to a padded buffer
 ```
 
+You can then parse the JSON document from the `simdjson::padded_string` instance:
+
+```cpp
+simdjson::dom::parser parser;
+simdjson::dom::element doc = parser.parse(my_padded_data);
+```
+
+Whenever you pass an `std::string` reference to `parser::parse`,
+the parser will access the bytes beyond the end of
+the string but before the end of the allocated memory (`std::string::capacity()`).
+If you are using a sanitizer that checks for reading uninitialized bytes or `std::string`'s
+container-overflow checks, you may encounter sanitizer warnings.
+You can safely ignore these warnings. Or you can call `simdjson::pad(std::string&)` to pad the
+string with `SIMDJSON_PADDING` spaces: this function returns a `simdjson::padding_string_view` which can be be passed to the parser's iterator function:
+
+```c++
+std::string json = "[1]";
+dom::element doc = parser.parse(simdjson::pad(json));
+```
+
 The parsed document resulting from the `parser.load` and `parser.parse` calls depends on the `parser` instance. Thus the `parser` instance must remain in scope. Furthermore, you must have at most one parsed document in play per `parser` instance.
 You cannot copy a `parser` instance, you may only move it.
 
@@ -69,7 +98,7 @@ During the`load` or `parse` calls, neither the input file nor the input string a
 For best performance, a `parser` instance should be reused over several files: otherwise you will needlessly reallocate memory, an expensive process. It is also possible to avoid entirely memory allocations during parsing when using simdjson. [See our performance notes for details](performance.md).
 
 If you need a lower-level interface, you may call the function `parser.parse(const char * p, size_t l)` on a pointer `p` while specifying the
-length of your input `l` in bytes. To see how to get the very best performance from a low-level approach, you way want to read our [performance notes](https://github.com/simdjson/simdjson/blob/master/doc/performance.md#padding-and-temporary-copies) on this topic (see the Padding and Temporary Copies section).
+length of your input `l` in bytes.
 
 *Windows-specific*:  Windows users who need to read files with
 non-ANSI characters in the name should set their code page to
@@ -98,6 +127,12 @@ Once you have an element, you can navigate it with idiomatic C++ iterators, oper
   std::cout << "I parsed " << value << " from " << numberstring.data() << std::endl;
   ```
   The strings contain unescaped valid UTF-8 strings: no unmatched surrogate is allowed.
+  Internally, numbers are stored as either 64-bit integers or 64-bit floating-point numbers.
+  Thus it is possible to get the full 64-bit integer range (either signed or  unsigned).
+  By default, the string `-0` is parsed as the integer 0 as in Pytho or C++. If you set the macro
+  `SIMDJSON_MINUS_ZERO_AS_FLOAT` to `1` when building simdjson, you can get that `-0` is mapped to `-0.0`
+  as in JavaScript. You can get the desired effect by building simdjson with cmake setting the
+  `SIMDJSON_MINUS_ZERO_AS_FLOAT` to on: `cmake -B build -D SIMDJSON_MINUS_ZERO_AS_FLOAT=ON`.
 * **Field Access:** To get the value of the "foo" field in an object, use `object["foo"]`.
 * **Array Iteration:** To iterate through an array, use `for (auto value : array) { ... }`. If you
   know the type of the value, you can cast it right there, too! `for (double value : array) { ... }`
@@ -211,6 +246,23 @@ for (dom::key_value_pair field : object) {
 }
 ```
 
+C++20 Support
+------------
+
+simdjson library also supports some C++20 feature including `std::ranges`:
+
+```c++
+auto cars_json = R"( [
+  { "make": "Toyota", "model": "Camry",  "year": 2018, "tire_pressure": [ 40.1, 39.9, 37.7, 40.4 ] },
+  { "make": "Kia",    "model": "Soul",   "year": 2012, "tire_pressure": [ 30.1, 31.0, 28.6, 28.7 ] },
+  { "make": "Toyota", "model": "Tercel", "year": 1999, "tire_pressure": [ 29.8, 30.0, 30.2, 30.5 ] }
+] )"_padded;
+dom::parser parser;
+auto justmodel = [](auto car) { return car["model"]; };
+for (auto car : parser.parse(cars_json).get_array() | std::views::transform(justmodel)) {
+  std::cout << car << std::endl;
+}
+```
 
 JSON Pointer
 ------------
@@ -257,6 +309,49 @@ for (dom::element car_element : cars) {
 }
 ```
 
+JSONPath
+------------
+
+
+The simdjson library supports a subset of [JSONPath](https://datatracker.ietf.org/doc/html/draft-normington-jsonpath-00) through the `at_path()` method, allowing you to reach further into the document in a single call. The subset of JSONPath that is implemented is the subset that is trivially convertible into the JSON Pointer format, using `.` to access a field and `[]` to access a specific index.
+
+Consider the following example:
+
+```c++
+auto cars_json = R"( [
+  { "make": "Toyota", "model": "Camry",  "year": 2018, "tire_pressure": [ 40.1, 39.9, 37.7, 40.4 ] },
+  { "make": "Kia",    "model": "Soul",   "year": 2012, "tire_pressure": [ 30.1, 31.0, 28.6, 28.7 ] },
+  { "make": "Toyota", "model": "Tercel", "year": 1999, "tire_pressure": [ 29.8, 30.0, 30.2, 30.5 ] }
+] )"_padded;
+dom::parser parser;
+dom::element doc;
+auto error = parser.parse(cars_json).get(doc);
+if(error) { /*won't happen*/ }
+double p;
+error = doc.at_path("[0].tire_pressure[1]").get(p);
+if(error) { /*won't happen*/ }
+cout << p << endl; // Prints 39.9
+```
+
+
+We also support the `$` prefix. When you start a JSONPath expression with $, you are indicating that the path starts from the root of the JSON document. E.g.,
+
+```c++
+auto json = R"( { "c" :{ "foo": { "a": [ 10, 20, 30 ] }}, "d": { "foo2": { "a": [ 10, 20, 30 ] }} , "e": 120 })"_padded;
+dom::parser parser;
+dom::element doc;
+auto error = parser.parse(json).get(doc);
+if(error) { /*won't happen*/ }
+dom::object obj;
+error = doc.get_object().get(obj);
+if(error) { /*won't happen*/ }
+int64_t x;
+error = obj.at_path("$[3].foo.a[1]").get(x);
+if(error) { /*won't happen*/ }
+if(x != 20) { /*won't happen*/ }
+x = obj.at_path("$.d.foo2.a.2");
+if(error) { /*won't happen*/ }
+```
 
 
 Error Handling
@@ -669,5 +764,5 @@ Setting the `realloc_if_needed` parameter `false` in this manner may lead to bet
 Performance Tips
 ---------------------
 
-- For release builds, we recommend setting `NDEBUG` pre-processor directive when compiling the `simdjson` library. Importantly, using the optimization flags `-O2` or `-O3` under GCC and LLVM clang does not set the `NDEBUG` directrive, you must set it manually (e.g., `-DNDEBUG`).
+- For release builds, we recommend setting `NDEBUG` pre-processor directive when compiling the `simdjson` library. Importantly, using the optimization flags `-O2` or `-O3` under GCC and LLVM clang does not set the `NDEBUG` directive, you must set it manually (e.g., `-DNDEBUG`).
 - For long streams of JSON documents, consider [`iterate_many`](iterate_many.md) and [`parse_many`](parse_many.md) for better performance.

doc/iterate_many.md

@@ -25,6 +25,7 @@ Contents
 - [Use cases](#use-cases)
 - [Tracking your position](#tracking-your-position)
 - [Incomplete streams](#incomplete-streams)
+- [C++20 features](#c20-features)
 
 Motivation
 -----------
@@ -102,7 +103,12 @@ remove almost entirely its cost and replaces it by the overhead of a thread, whi
 cheaper. Ain't that awesome!
 
 Thread support is only active if thread supported is detected in which case the macro
-SIMDJSON_THREADS_ENABLED is set. Otherwise the library runs in  single-thread mode.
+SIMDJSON_THREADS_ENABLED is set.  You can also manually pass `SIMDJSON_THREADS_ENABLED=1` flag
+to the library. Otherwise the library runs in single-thread mode.
+
+You should be consistent. If you link against the simdjson library built for multithreading
+(i.e., with `SIMDJSON_THREADS_ENABLED`), then you should build your application with multithreading
+system (setting `SIMDJSON_THREADS_ENABLED=1` and linking against a thread library).
 
 A `document_stream` instance uses at most two threads: there is a main thread and a worker thread.
 
@@ -124,7 +130,7 @@ If your documents are all objects or arrays, then you may even have nothing betw
 E.g., `[1,2]{"32":1}` is recognized as two documents.
 
 Some official formats **(non-exhaustive list)**:
-- [Newline-Delimited JSON (NDJSON)](http://ndjson.org/)
+- [Newline-Delimited JSON (NDJSON)](https://github.com/ndjson/ndjson-spec/)
 - [JSON lines (JSONL)](http://jsonlines.org/)
 - [Record separator-delimited JSON (RFC 7464)](https://tools.ietf.org/html/rfc7464) <- Not supported by JsonStream!
 - [More on Wikipedia...](https://en.wikipedia.org/wiki/JSON_streaming)
@@ -288,3 +294,111 @@ string
 object
 array
 ```
+
+
+C++20 features
+--------------------
+
+In C++20, the standard introduced the notion of *customization point*.
+A customization point is a function or function object that can be customized for different types. It allows library authors to provide default behavior while giving users the ability to override this behavior for specific types.
+
+A tag_invoke function serves as a mechanism for customization points. It is not directly part of the C++ standard library but is often used in libraries that implement customization points.
+The tag_invoke function is typically a generic function that takes a tag type and additional arguments.
+The first argument is usually a tag type (often an empty struct) that uniquely identifies the customization point (e.g., deserialization of custom types in simdjson). Users or library providers can specialize tag_invoke for their types by defining it in the appropriate namespace, often inline namespace.
+
+
+
+You can deserialize you own data structures conveniently if your system supports C++20.
+When it is the case, the macro `SIMDJSON_SUPPORTS_DESERIALIZATION` will be set to 1 by
+the simdjson library.
+
+Consider a custom class `Car`:
+
+```C++
+struct Car {
+  std::string make;
+  std::string model;
+  int year;
+  std::vector<float> tire_pressure;
+};
+```
+
+
+You may support deserializing directly from a JSON value or document to your own `Car` instance
+by defining a single `tag_invoke` function:
+
+
+```C++
+namespace simdjson {
+// This tag_invoke MUST be inside simdjson namespace
+template <typename simdjson_value>
+auto tag_invoke(deserialize_tag, simdjson_value &val, Car& car) {
+  ondemand::object obj;
+  auto error = val.get_object().get(obj);
+  if (error) {
+    return error;
+  }
+  if ((error = obj["make"].get_string(car.make))) {
+    return error;
+  }
+  if ((error = obj["model"].get_string(car.model))) {
+    return error;
+  }
+  if ((error = obj["year"].get(car.year))) {
+    return error;
+  }
+  if ((error = obj["tire_pressure"].get<std::vector<float>>().get(
+           car.tire_pressure))) {
+    return error;
+  }
+  return simdjson::SUCCESS;
+}
+} // namespace simdjson
+```
+
+Importantly, the `tag_invoke` function must be inside the `simdjson` namespace.
+Let us explain each argument of `tag_invoke` function.
+
+- `simdjson::deserialize_tag`: it is the tag for Customization Point Object (CPO). You may often ignore this parameter. It is used to indicate that you mean to provide a deserialization function for simdjson.
+- `var`: It receives automatically a `simdjson` value type (document, value, document_reference).
+- The third parameter is an instance of the type that you want to support.
+
+Please see our main documentation (`basics.md`) under
+"Use `tag_invoke` for custom types (C++20)" for details about
+tag_invoke functions.
+
+Given a stream of JSON documents, you can add them to a data structure
+such as a `std::vector<Car>` like so if you support exceptions:
+
+```C++
+  padded_string json =
+      R"( { "make": "Toyota", "model": "Camry",  "year": 2018,
+       "tire_pressure": [ 40.1, 39.9 ] }
+  { "make": "Kia",    "model": "Soul",   "year": 2012,
+       "tire_pressure": [ 30.1, 31.0 ] }
+  { "make": "Toyota", "model": "Tercel", "year": 1999,
+       "tire_pressure": [ 29.8, 30.0 ] }
+)"_padded;
+  ondemand::parser parser;
+  ondemand::document_stream stream;
+  [[maybe_unused]] auto error = parser.iterate_many(json).get(stream);
+  std::vector<Car> cars;
+  for(auto doc : stream) {
+    cars.push_back((Car)doc); // an exception may be thrown
+  }
+```
+
+Otherwise you may use this longer version for explicit handling of errors:
+
+
+```C++
+  std::vector<Car> cars;
+  for(auto doc : stream) {
+    Car c;
+    if ((error = doc.get<Car>().get(c))) {
+      std::cerr << simdjson::error_message(error); << std::endl;
+      return EXIT_FAILURE;
+    }
+    cars.push_back(c);
+  }
+```

doc/ondemand_design.md

@@ -9,8 +9,8 @@ Whether we parse JSON or XML, or any other serialized format, there are relative
 - Another popular approach is the schema-based deserialization model.
 
 We propose an approach that is as easy to use and often as flexible as the DOM approach, yet as fast and
-efficient as the schema-based or event-based approaches. We call this new approach "On Demand". The
-simdjson On Demand API offers a familiar, friendly DOM API and
+efficient as the schema-based or event-based approaches. We call this new approach "On-Demand". The
+simdjson On-Demand API offers a familiar, friendly DOM API and
 provides the performance of just-in-time parsing on top of the simdjson superior performance.
 
 To achieve ease of use, we mimicked the *form* of a traditional DOM API: you can iterate over
@@ -18,7 +18,7 @@ arrays, look up fields in objects, and extract native values like `double`, `uin
 
 To achieve performance, we introduced some key limitations that make the DOM API *streaming*:
 array/object iteration cannot be restarted, and string/number values can only be parsed once. If
-these limitations are acceptable to you, the On Demand API could help you write maintainable
+these limitations are acceptable to you, the On-Demand API could help you write maintainable
 applications with a computation efficiency that is difficult to surpass.
 
 A code example illustrates our API from a programmer's point of view:
@@ -72,24 +72,24 @@ This streaming approach means that unused fields and values are not parsed or
 converted, thus saving space and time. In our example, the `"name"`, `"followers_count"`,
 and `"friends_count"` keys and matching values are skipped.
 
-Further, the On Demand API does not parse a value *at all* until you try to convert it (e.g., to `double`,
+Further, the On-Demand API does not parse a value *at all* until you try to convert it (e.g., to `double`,
 `int`, `string`, or `bool`). In our example, when accessing the key-value pair `"retweet_count": 82`, the parser
 may not convert the pair of characters `82` to the binary integer 82. Because the programmer specifies the data
 type, we avoid branch mispredictions related to data type determination and improve the performance.
 
 
-We expect users of an On Demand API to work in terms of a JSON dialect, which is a set of expectations and
+We expect users of an On-Demand API to work in terms of a JSON dialect, which is a set of expectations and
 specifications that come in addition to the [JSON specification](https://www.rfc-editor.org/rfc/rfc8259.txt).
-The On Demand approach is designed around several principles:
+The On-Demand approach is designed around several principles:
 
 * **Streaming (\*):** It avoids preparsing values, keeping the memory usage and the latency down.
 * **Forward-Only:** To prevent reiteration of the same values and to keep the number of variables down (literally), only a single index is maintained and everything uses it (even if you have nested for loops). This means when you are going through an array of arrays, for example, that the inner array loop will advance the index to the next comma, and the array can just pick it up and look at it.
 * **Natural Iteration:** A JSON array or object can be iterated with a normal C++ for loop. Nested arrays and objects are supported by nested for loops.
 * **Use-Specific Parsing:** Parsing is always specific to the type required by the programmer. For example, if the programmer asks for an unsigned integer, we just start parsing digits. If there were no digits, we toss an error. There are even different parsers for `double`, `uint64_t` and `int64_t` values. This use-specific parsing avoids the branchiness of a generic "type switch," and makes the code more inlineable and compact.
-* **Validate What You Use:** On Demand deliberately validates the values you use and the structure leading to it, but nothing else. The goal is a guarantee that the value you asked for is the correct one and is not malformed: there must be no confusion over whether you got the right value.
+* **Validate What You Use:** On-Demand deliberately validates the values you use and the structure leading to it, but nothing else. The goal is a guarantee that the value you asked for is the correct one and is not malformed: there must be no confusion over whether you got the right value.
 
 
-To understand why On Demand is different, it is helpful to review the major
+To understand why On-Demand is different, it is helpful to review the major
 approaches to parsing and parser APIs in use today.
 
 ### DOM Parsers
@@ -102,11 +102,11 @@ or indexing (`object["key"]`). In some cases, the values are even deserialized d
 maps.
 
 The DOM approach is conceptually simple and "programmer friendly". Using the
-DOM tree is often easy enough that many users use the DOM as-is instead of creating
+DOM tree is often easy enough that many users process the DOM as-is instead of creating
 their own custom data structures.
 
 The DOM approach was the only way to parse JSON documents up to version 0.6 of the simdjson library.
-Our DOM API looks similar to our On Demand example, except
+Our DOM API looks similar to our On-Demand example, except
 it calls `parse` instead of `iterate`:
 
 ```c++
@@ -152,7 +152,7 @@ a tweet right now, or is this from some other place in the document
 entirely? Though an event-based approach may allow superior performance, it is demanding of the programmer
 who must efficiently keep track of its current state within the JSON input.
 
-The following is event-based example of the Twitter problem we have reviewed in the DOM and On Demand
+The following is event-based example of the Twitter problem we have reviewed in the DOM and On-Demand
 examples. To make it short enough to use as an example at all, it has heavily redacted: it only solves
 a part of the problem (does not get user.screen_name), it has bugs (it does not handle sub-objects
 in a tweet at all), and it uses a theoretical, simple event-based API that minimizes ceremony.
@@ -257,7 +257,7 @@ stress the branch prediction. Though branch predictors improve with each new gen
 the cost of branch mispredictions also tends to increase as pipelines expand, and the processors become
 able to schedule longer streams of instructions.
 
-On Demand parsing is tailor-made to solve this problem at the source, parsing values only after the
+On-Demand parsing is tailor-made to solve this problem at the source, parsing values only after the
 user declares their type by asking for a `double`, an `int`, a `string`, etc. It attempts to do so while
 preserving most of the flexibility of DOM parsing.
 
@@ -297,7 +297,7 @@ To help visualize the algorithm, we'll walk through the example C++ given at the
 
    Since this is the first time this parser has been used, `iterate()` first allocates internal
    parser buffers if this is the first time through. When reusing an existing parser, allocation
-   only happens if the new document is bigger than internal buffers can handle. The On Demand
+   only happens if the new document is bigger than internal buffers can handle. The On-Demand
    API only ever allocates memory in the `iterate()` function call.
 
    The simdjson library then preprocesses the JSON text at high speed, finding all tokens (i.e. the starting
@@ -492,7 +492,7 @@ To help visualize the algorithm, we'll walk through the example C++ given at the
    Because of the cast to uint64_t, simdjson knows it's parsing an unsigned integer. This lets
    us use a fast parser which *only* knows how to parse digits. It validates that it is an integer
    by rejecting negative numbers, strings, and other values based on the fact that they are not the
-   digits 0-9. This type specificity is part of why parsing with on demand is so fast: you lose all
+   digits 0-9. This type specificity is part of why parsing with On-Demand is so fast: you lose all
    the code that has to understand those other types.
 
    The iterator is advanced to the `}`, and depth decreased back to 3 (root > statuses > tweet).
@@ -597,7 +597,7 @@ To help visualize the algorithm, we'll walk through the example C++ given at the
 
    This means you can very efficiently do things like read a single value from a JSON file, or take
    the top N, for example. It also means the things you don't use won't be fully validated. This is
-   a general principle of On Demand: don't validate what you don't use. We still fully validate
+   a general principle of On-Demand: don't validate what you don't use. We still fully validate
    values you do use, however, as well as the objects and arrays that lead to them, so that you can
    be sure you get the information you need.
 
@@ -654,7 +654,7 @@ for(auto field : doc.get_object())  {
 
 ### Iteration Safety
 
-The On Demand API is powerful. To compensate, we add some safeguards to ensure that it can be used without fear
+The On-Demand API is powerful. To compensate, we add some safeguards to ensure that it can be used without fear
 in production systems:
 
   - If the value fails to be parsed as one type, the program can try to parse it as something else until the program succeeds. Thus
@@ -667,7 +667,7 @@ in production systems:
     if it was `nullptr` but did not care what the actual value was--it will iterate. The destructor automates
     the iteration.
 
-  Some care is needed when using the On Demand API in scenarios where you need to access several sibling arrays or objects because
+  Some care is needed when using the On-Demand API in scenarios where you need to access several sibling arrays or objects because
   only one object or array can be active at any one time. Let us consider the following example:
 
 ```C++
@@ -709,36 +709,36 @@ A correct usage is given by the following example:
     }
 ```
 
-### Benefits of the On Demand Approach
+### Benefits of the On-Demand Approach
 
-We expect that the On Demand approach has many of the performance benefits of the schema-based approach, while providing a flexibility that is similar to that of the DOM-based approach.
+We expect that the On-Demand approach has many of the performance benefits of the schema-based approach, while providing a flexibility that is similar to that of the DOM-based approach.
 
 * Faster than DOM in some cases. Reduced memory usage.
 * Straightforward, programmer-friendly interface (arrays and objects).
 * Highly expressive, beyond deserialization and pointer queries: many tasks can be accomplished with little code.
 
-### Limitations of the On Demand Approach
+### Limitations of the On-Demand Approach
 
-The On Demand approach has some limitations:
+The On-Demand approach has some limitations:
 
 * Because it operates in streaming mode, you only have access to the current element in the JSON document. Furthermore, the document is traversed in order so the code is sensitive to the order of the JSON nodes in the same manner as an event-based approach (e.g., SAX). (The one exception to this is field lookup, which is more *performant* when the order of lookups matches the order of fields in the document, but which will still work with out-of-order fields, with a performance hit.)
-* The On Demand approach is less safe than DOM: we only validate the components of the JSON document that are used and it is possible to begin ingesting an invalid document only to find out later that the document is invalid. Are you fine ingesting a large JSON document that starts with well formed JSON but ends with invalid JSON content?
+* The On-Demand approach is less safe than DOM: we only validate the components of the JSON document that are used and it is possible to begin ingesting an invalid document only to find out later that the document is invalid. Are you fine ingesting a large JSON document that starts with well formed JSON but ends with invalid JSON content?
 
 There are currently additional technical limitations which we expect to resolve in future releases of the simdjson library:
 
-* The simdjson library offers runtime dispatching which allows you to compile one binary and have it run at full speed on different processors, taking advantage of the specific features of the processor. The On Demand API has limited runtime dispatch support. Under x64 systems, to fully benefit from the On Demand API, we recommend that you compile your code for a specific processor. E.g., if your processor supports AVX2 instructions, you should compile your binary executable with AVX2 instruction support (by using your compiler's commands). If you are sufficiently technically proficient, you can implement runtime dispatching within your application, by compiling your On Demand code for different processors.
+* The simdjson library offers runtime dispatching which allows you to compile one binary and have it run at full speed on different processors, taking advantage of the specific features of the processor. The On-Demand API has limited runtime dispatch support. Under x64 systems, to fully benefit from the On-Demand API, we recommend that you compile your code for a specific processor. E.g., if your processor supports AVX2 instructions, you should compile your binary executable with AVX2 instruction support (by using your compiler's commands). If you are sufficiently technically proficient, you can implement runtime dispatching within your application, by compiling your On-Demand code for different processors.
 * There is an initial phase which scans the entire document quickly, irrespective of the size of the document. We plan to break this phase into distinct steps for large files in a future release as we have done with other components of our API (e.g., `parse_many`).
 
-### Applicability of the On Demand Approach
+### Applicability of the On-Demand Approach
 
-At this time we recommend the On Demand API in the following cases:
+At this time we recommend the On-Demand API in the following cases:
 
 1. The 64-bit hardware (CPU) used to run the software is known at compile time. If you need runtime dispatching because you cannot be certain of the hardware used to run your software, you will be better served with the core simdjson API. (This only applies to x64 (AMD/Intel). On 64-bit ARM hardware, runtime dispatching is unnecessary.)
 2. The used parts of JSON files do not need to be validated and the layout of the nodes follows a strict JSON dialect. If you are receiving JSON from other systems, you might be better served with core simdjson API as it fully validates the JSON inputs and allows you to navigate through the document at will.
-3. Speed and efficiency are of the utmost importance. Keep in mind that the core simdjson API is highly efficient so adopting the On Demand API is not necessary for high efficiency.
+3. Speed and efficiency are of the utmost importance. Keep in mind that the core simdjson API is highly efficient so adopting the On-Demand API is not necessary for high efficiency.
 4. As a developer, you value a clean, flexible and maintainable API.
 
-Good applications for the On Demand API might be:
+Good applications for the On-Demand API might be:
 
 * You are working from pre-existing large JSON files that have been vetted. You expect them to be well formed according to a known JSON dialect and to have a consistent layout. For example, you might be doing biomedical research or machine learning on top of static data dumps in JSON.
 * Both the generation and the consumption of JSON data is within your system. Your team controls both the software that produces the JSON and the software the parses it, your team knows and control the hardware. Thus you can fully test your system.
@@ -746,13 +746,13 @@ Good applications for the On Demand API might be:
 
 ## Checking Your CPU Selection (x64 systems)
 
-The On Demand API uses advanced architecture-specific code for many common processors to make JSON preprocessing and string parsing faster. By default, however, most c++ compilers will compile to the	least common denominator (since the program could theoretically be run anywhere). Since On Demand is inlined into your own code, it cannot always use these advanced versions unless the compiler is told to target them.
+The On-Demand API uses advanced architecture-specific code for many common processors to make JSON preprocessing and string parsing faster. By default, however, most c++ compilers will compile to the	least common denominator (since the program could theoretically be run anywhere). Since On-Demand is inlined into your own code, it cannot always use these advanced versions unless the compiler is told to target them.
 
-On relevant systems, the On Demand API provides some support for runtime dispatching: that is, it will attempt to detect, at runtime, the instructions that your processor supports and optimize the code accordingly. However, it cannot always make full use of the features of your processor.
+On relevant systems, the On-Demand API provides some support for runtime dispatching: that is, it will attempt to detect, at runtime, the instructions that your processor supports and optimize the code accordingly. However, it cannot always make full use of the features of your processor.
 
 Some users wish to run at the best possible speed. Under recent Intel and AMD processors, these users should take additional steps to verify that their code is well optimized.
 
-Given that the On Demand API offer limited runtime dispatching, it matters that your code is compiled against a specific CPU target. You should verify that the code is compiled against the target you expect. Thankfully, the simdjson library will tell you exactly what it detects as an implementation: `icelake` (AVX512 x64 processors), `haswell` (AVX2 x64 processors), `westmere` (SSE4 x64 processors), `arm64` (64-bit ARM), `ppc64` (64-bit POWER), `lasx` (LoongArch), `lsx` (LoongArch),  `fallback` (others). Under x64 processors, many programmers will want to target `haswell` whereas under ARM, most programmers will want to target `arm64` (and it should do so automatically). The `fallback` is probably only good for testing purposes, not for deployment.
+Given that the On-Demand API offer limited runtime dispatching, it matters that your code is compiled against a specific CPU target. You should verify that the code is compiled against the target you expect. Thankfully, the simdjson library will tell you exactly what it detects as an implementation: `icelake` (AVX512 x64 processors), `haswell` (AVX2 x64 processors), `westmere` (SSE4 x64 processors), `arm64` (64-bit ARM), `ppc64` (64-bit POWER), `lasx` (LoongArch), `lsx` (LoongArch),  `fallback` (others). Under x64 processors, many programmers will want to target `haswell` whereas under ARM, most programmers will want to target `arm64` (and it should do so automatically). The `fallback` is probably only good for testing purposes, not for deployment.
 
 ```C++
   std::cout << simdjson::builtin_implementation()->name() << std::endl;
@@ -777,6 +777,6 @@ In these examples, the `-march=haswell` flags targets a haswell processor and th
 
 Instead of specifying a specific microarchitecture, you can let your compiler do the work. The `-march=native` flags says "target the current computer," which is a reasonable default for many applications which both compile and run on the same processor.
 
-Passing `-march=native` to the compiler may make On Demand faster by allowing it to use optimizations specific to your machine. You cannot do this, however, if you are compiling code	that might be run on less advanced machines. That is, be mindful that when compiling with the `-march=native` flag, the resulting binary will run on the current system but may not run on other systems (e.g., on an old processor).
+Passing `-march=native` to the compiler may make On-Demand faster by allowing it to use optimizations specific to your machine. You cannot do this, however, if you are compiling code	that might be run on less advanced machines. That is, be mindful that when compiling with the `-march=native` flag, the resulting binary will run on the current system but may not run on other systems (e.g., on an old processor).
 
 If you are compiling on an ARM or POWER system, you do not need to be concerned with CPU selection during compilation. The `-march=native` flag is useful for best performance on x64 (e.g., Intel) systems but it is generally unsupported on some platforms such as ARM (aarch64) or POWER.

doc/parse_many.md

@@ -103,7 +103,12 @@ cases, remove almost entirely its cost and replaces it by the overhead of a thre
 of magnitude cheaper. Ain't that awesome!
 
 Thread support is only active if thread supported is detected in which case the macro
-SIMDJSON_THREADS_ENABLED is set. Otherwise the library runs in  single-thread mode.
+SIMDJSON_THREADS_ENABLED is set.  You can also manually pass `SIMDJSON_THREADS_ENABLED=1` flag
+to the library. Otherwise the library runs in single-thread mode.
+
+You should be consistent. If you link against the simdjson library built for multithreading
+(i.e., with `SIMDJSON_THREADS_ENABLED`), then you should build your application with multithreading
+system (setting `SIMDJSON_THREADS_ENABLED=1` and linking against a thread library).
 
 A `document_stream` instance uses at most two threads: there is a main thread and a worker thread.
 You should expect the main thread to be fully occupied while the worker thread is partially busy
@@ -125,7 +130,7 @@ Whitespace Characters:
 - **Nothing**
 
 Some official formats **(non-exhaustive list)**:
-- [Newline-Delimited JSON (NDJSON)](http://ndjson.org/)
+- [Newline-Delimited JSON (NDJSON)](https://github.com/ndjson/ndjson-spec)
 - [JSON lines (JSONL)](http://jsonlines.org/)
 - [Record separator-delimited JSON (RFC 7464)](https://tools.ietf.org/html/rfc7464) <- Not supported by JsonStream!
 - [More on Wikipedia...](https://en.wikipedia.org/wiki/JSON_streaming)

doc/performance.md

@@ -4,9 +4,9 @@ Performance Notes
 simdjson strives to be at its fastest *without tuning*, and generally achieves this. However, there
 are still some scenarios where tuning can enhance performance.
 Once your code is tested, we
-further encourage you to define `NDEBUG` in your Release builds to disable additional runtime
+further encourage you to define `NDEBUG` in your release builds to disable additional runtime
 testing and get the best performance.
-* [NDEBUG directive](#ndebug-directive)
+* [NDEBUG macro](#ndebug-macro)
 * [Reusing the parser for maximum efficiency](#reusing-the-parser-for-maximum-efficiency)
 * [Reusing string buffers](#reusing-string-buffers)
 * [Server Loops: Long-Running Processes and Memory Capacity](#server-loops-long-running-processes-and-memory-capacity)
@@ -14,18 +14,30 @@ testing and get the best performance.
 * [Number parsing](#number-parsing)
 * [Visual Studio](#visual-studio)
 * [Power Usage and Downclocking](#power-usage-and-downclocking)
+* [Free Padding](#free-padding)
 
 
-NDEBUG directive
+NDEBUG macro
 -------------
 
-In C/C++, the `NDEBUG` pre-processor directive is not set by default. When it is not set, the simdjson library does
-many additional checks that may impact negatively the performance. We recommend that, once your code
-is well tested, you define `NDEBUG` directive in your Release builds. The `NDEBUG` directive should be defined
-prior to including the `simdjson.h` header.
+We recommend that you set `NDEBUG` macro in your release builds.
 
-The `NDEBUG` directive is generally independent from optimization flags. For example, setting `-O3` under
-GCC does not set the `NDEBUG` directive.
+In C/C++, the `NDEBUG` macro is not set by default.
+When it is not set, the software may do many additional checks that may impact
+negatively the performance. We recommend that, once your code
+is well tested, you define `NDEBUG` directive in your release builds.
+
+The `NDEBUG` directive is generally independent from optimization flags.
+For example, setting `-O3` under GCC does not set the `NDEBUG` directive.
+However, tools like `CMake` automatically
+set `NDEBUG` for release builds.
+
+In the simdjson library, we check the `NDEBUG` macro as well as other
+macros to make performant release builds. However, the C++ standard
+does not provide a definitive approach to determine whether you are
+compiling for a release build. Thus we recommend that you follow
+the practice of setting the `NDEBUG` macro in release mode to make sure
+that you do not get undesirable expensive checks.
 
 Reusing the parser for maximum efficiency
 -----------------------------------------
@@ -74,7 +86,7 @@ or simply
 Server Loops: Long-Running Processes and Memory Capacity
 ---------------------------------
 
-The On Demand approach also automatically expands its memory capacity when larger documents are parsed. However, for longer processes where very large files are processed (such as server loops), this capacity is not resized down. On Demand also lets you adjust the maximal capacity that the parser can process:
+The On-Demand approach also automatically expands its memory capacity when larger documents are parsed. However, for longer processes where very large files are processed (such as server loops), this capacity is not resized down. On-Demand also lets you adjust the maximal capacity that the parser can process:
 
 * You can set an upper bound (*max_capacity*) when construction the parser:
 ```C++
@@ -157,7 +169,9 @@ On Intel and AMD Windows platforms, Microsoft Visual Studio enables programmers
 
 When compiling with Visual Studio, we recommend the flags `/Ob2 /O2` or better. We do not recommend that you compile simdjson with architecture-specific flags such as  `arch:AVX2`. The simdjson library automatically selects the best execution kernel at runtime.
 
-Recent versions of Microsoft Visual Studio on Windows provides support for the LLVM Clang compiler. You  only need to install the "Clang compiler" optional component (ClangCL). You may also get a copy of the 64-bit LLVM CLang compiler for [Windows directly from LLVM](https://releases.llvm.org/download.html). The simdjson library fully supports the LLVM Clang compiler under Windows. In fact, you may get better performance out of simdjson with the LLVM Clang compiler than with the regular Visual Studio compiler. Meanwhile the [LLVM CLang compiler is binary compatible with Visual Studio](https://clang.llvm.org/docs/MSVCCompatibility.html) which means that you can combine their binaries (executables and libraries).
+Recent versions of Microsoft Visual Studio on Windows provides support for the LLVM Clang compiler. You  only need to install the "Clang compiler" optional component (clang-cl). You may also get a copy of the 64-bit LLVM CLang compiler for [Windows directly from LLVM](https://releases.llvm.org/download.html). The simdjson library fully supports the LLVM Clang compiler under Windows. In fact, you may get better performance out of simdjson with the LLVM Clang compiler than with the regular Visual Studio compiler. Meanwhile the [LLVM CLang compiler is binary compatible with Visual Studio](https://clang.llvm.org/docs/MSVCCompatibility.html) which means that you can combine their binaries (executables and libraries).
+
+We recommend Visual Studio users prefer LLVM (clang-cl). It compiles to faster release binaries. Furthermore, it compilers faster in release mode.
 
 Under Windows, we also support the GNU GCC compiler via MSYS2. The performance of 64-bit MSYS2 under Windows is excellent (on par with Linux).
 
@@ -179,3 +193,110 @@ The simdjson library does not generally make use of heavy 256-bit instructions.
 the macro `SIMDJSON_AVX512_ALLOWED` to `0` in C++ prior to importing the headers.
 
 You may still be worried about which SIMD instruction set is used by simdjson.  Thankfully,  [you can always determine and change which architecture-specific implementation is used](implementation-selection.md) by simdjson. Thus even if your CPU supports AVX2, you do not need to use AVX2. You are in control.
+
+
+Free Padding
+-------
+
+For performance reasons, the simdjson library requires that the JSON input contain at least
+`simdjson::SIMDJSON_PADDING` bytes at the end of the stream. The value `simdjson::SIMDJSON_PADDING` is
+small (e.g., 64 bytes). On modern systems, you can safely read beyond an allocated buffers,
+as long as you remain within an allocated page. Pages on modern systems span at least 4 kilobytes,
+but can be significantly larger. E.g., Apple systems favour pages spanning 16 kilobytes.
+
+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.
+
+
+The conditional compilation checks for the `_MSC_VER` macro (indicating Microsoft Visual Studio)
+and includes platform-specific headers accordingly.
+The `page_size()` function determines the default size of a memory page in bytes on the system.
+On Windows (when `_WIN32` is defined), it uses `GetSystemInfo()` to retrieve system information and obtain the page size.
+On other platforms (non-Windows), it uses `sysconf(_SC_PAGESIZE)` to get the page size.
+The function returns the page size.
+The `need_allocation()` function checks whether the buffer (given by `buf`) plus the specified length (`len`) is near a page boundary.
+If the buffer extends beyond the current page when padded by `simdjson::SIMDJSON_PADDING`, it returns true, indicating that reallocation is needed.
+Otherwise, it returns false.
+The `get_padded_string_view()`  creates a `padded_string_view` from the input buffer.
+If reallocation is needed (unlikely case), it allocates a new padded_string and assigns it to `jsonbuffer`.
+Otherwise (very likely), it creates a `padded_string_view` directly from the buffer.
+The `simdjson::SIMDJSON_PADDING` ensures that there is additional padding for parsing efficiency.
+The calling code just needs to provide `jsonbuffer` (an instance of `simdjson::padded_string`)
+and pass `get_padded_string_view(buf, len, jsonbuffer)` to  `parser.iterate`. Most of the time,
+this code will not allocate new memory.
+
+
+```cpp
+#ifdef _WIN32
+#include <windows.h>
+#include <sysinfoapi.h>
+#else
+#include <unistd.h>
+#endif
+#include "simdjson.h"
+#include <cstdio>
+
+// Returns the default size of the page in bytes on this system.
+long page_size() {
+#ifdef _WIN32
+  SYSTEM_INFO sysInfo;
+  GetSystemInfo(&sysInfo);
+  long pagesize = sysInfo.dwPageSize;
+#else
+  long pagesize = sysconf(_SC_PAGESIZE);
+#endif
+  return pagesize;
+}
+
+// Returns true if the buffer + len + simdjson::SIMDJSON_PADDING crosses the
+// page boundary.
+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()));
+}
+
+simdjson::padded_string_view
+get_padded_string_view(const char *buf, size_t len,
+                       simdjson::padded_string &jsonbuffer) {
+  if (need_allocation(buf, len)) { // unlikely case
+    jsonbuffer = simdjson::padded_string(buf, len);
+    return jsonbuffer;
+  } else { // no reallcation needed (very likely)
+    return simdjson::padded_string_view(buf, len,
+                                            len + simdjson::SIMDJSON_PADDING);
+  }
+}
+
+int main() {
+  printf("page_size: %ld\n", page_size());
+  const char *jsonpoiner = R"(
+        {
+            "key": "value"
+        }
+    )";
+  size_t len = strlen(jsonpoiner);
+  simdjson::padded_string jsonbuffer; // only allocate if needed
+  simdjson::ondemand::parser parser;
+  simdjson::ondemand::document doc;
+  simdjson::error_code error =
+      parser.iterate(get_padded_string_view(jsonpoiner, len, jsonbuffer))
+          .get(doc);
+  if (error) {
+    printf("error: %s\n", simdjson::error_message(error));
+    return EXIT_FAILURE;
+  }
+  std::string_view value;
+  error = doc["key"].get_string().get(value);
+  if (error) {
+    return EXIT_FAILURE;
+  }
+  printf("Value: \"%.*s\"\n", (int)value.size(), value.data());
+  if (value != "value") {
+    return EXIT_FAILURE;
+  }
+  return EXIT_SUCCESS;
+}
+```

examples/BUILD_INSTRUCTIONS.md

@@ -0,0 +1,254 @@
+# 🛠️ Build Instructions for simdjson One-Liner Demo
+
+## Prerequisites
+
+### For Both Examples
+- **cpr library** (for HTTP requests) - See [INSTALL_CPR.md](INSTALL_CPR.md) for installation
+- **curl library** (cpr dependency) - Usually pre-installed on most systems
+- **simdjson library** - Included in this repository
+
+### For Legacy Example (github_legacy.cpp)
+- Any C++20 compatible compiler (GCC 10+, Clang 10+, MSVC 2019+)
+
+### For Modern Example (github_modern.cpp)  
+- Bloomberg Clang fork with C++26 reflection support
+  - Get it from: https://github.com/bloomberg/clang-p2996
+
+## 🔨 Compilation Commands
+
+### Quick Setup (Recommended)
+
+1. **Build cpr from source** (if not installed system-wide):
+```bash
+# From the examples directory
+mkdir -p ../deps && cd ../deps
+git clone https://github.com/libcpr/cpr.git
+cd cpr && git checkout 1.10.5
+mkdir build && cd build
+cmake .. -DCMAKE_CXX_COMPILER=clang++ -DCPR_USE_SYSTEM_CURL=ON -DBUILD_SHARED_LIBS=OFF -DCPR_ENABLE_SSL=OFF
+make -j4
+cd ../../../examples
+```
+
+2. **Compile the examples**:
+```bash
+# Legacy approach (any C++20 compiler)
+clang++ -std=c++20 \
+  -I../deps/cpr/include \
+  -I../deps/cpr/build/cpr_generated_includes \
+  -I../include -I.. \
+  github_legacy.cpp \
+  ../singleheader/simdjson.cpp \
+  ../deps/cpr/build/lib/libcpr.a \
+  -lcurl -pthread \
+  -o github_legacy_demo
+
+# Modern approach (Bloomberg clang with reflection)
+clang++ -std=c++26 -freflection \
+  -DSIMDJSON_STATIC_REFLECTION=1 \
+  -I../deps/cpr/include \
+  -I../deps/cpr/build/cpr_generated_includes \
+  -I../include -I.. \
+  github_modern.cpp \
+  ../singleheader/simdjson.cpp \
+  ../deps/cpr/build/lib/libcpr.a \
+  -lcurl -pthread \
+  -o github_modern_demo
+```
+
+### Using System-Installed cpr
+
+If cpr is installed system-wide (see [INSTALL_CPR.md](INSTALL_CPR.md)):
+
+```bash
+# Legacy approach
+clang++ -std=c++20 \
+  -I../include -I.. \
+  github_legacy.cpp \
+  -lcpr -lcurl \
+  -o github_legacy_demo
+
+# Modern approach
+clang++ -std=c++26 -freflection \
+  -DSIMDJSON_STATIC_REFLECTION=1 \
+  -I../include -I.. \
+  github_modern.cpp \
+  -lcpr -lcurl \
+  -o github_modern_demo
+```
+
+### Using simdjson Single Header
+
+```bash
+# Legacy approach
+clang++ -std=c++20 \
+  -I../singleheader \
+  github_legacy.cpp \
+  ../singleheader/simdjson.cpp \
+  -lcpr -lcurl \
+  -o github_legacy_demo
+
+# Modern approach
+clang++ -std=c++26 -freflection \
+  -DSIMDJSON_STATIC_REFLECTION=1 \
+  -I../singleheader -I../include \
+  github_modern.cpp \
+  ../singleheader/simdjson.cpp \
+  -lcpr -lcurl \
+  -o github_modern_demo
+```
+
+### Using CMake (Recommended)
+
+```bash
+# Create build directory
+mkdir build && cd build
+
+# Configure with CMake
+cmake .. -DCMAKE_CXX_COMPILER=clang++ \
+         -DCMAKE_CXX_STANDARD=26 \
+         -DCMAKE_CXX_FLAGS="-freflection -DSIMDJSON_STATIC_REFLECTION=1"
+
+# Build both examples
+make github_legacy github_modern
+```
+
+### Quick Build with simdjson Single Header
+
+```bash
+# Legacy approach
+clang++ -std=c++20 \
+  -I../singleheader \
+  github_legacy.cpp \
+  ../singleheader/simdjson.cpp \
+  -lcpr -lcurl \
+  -o github_legacy_demo
+
+# Modern approach  
+clang++ -std=c++26 -freflection \
+  -DSIMDJSON_STATIC_REFLECTION=1 \
+  -I../singleheader \
+  github_modern.cpp \
+  ../singleheader/simdjson.cpp \
+  -lcpr -lcurl \
+  -o github_modern_demo
+```
+
+## 🏃 Running the Examples
+
+```bash
+# Run legacy version
+./github_legacy_demo
+
+# Run modern version  
+./github_modern_demo
+```
+
+## 🎯 Platform-Specific Notes
+
+### Linux (x86_64)
+```bash
+-DSIMDJSON_IMPLEMENTATION_HASWELL=1
+```
+
+### Linux (ARM64)
+```bash
+-DSIMDJSON_IMPLEMENTATION_ARM64=1
+```
+
+### macOS (Apple Silicon)
+```bash
+-DSIMDJSON_IMPLEMENTATION_ARM64=1
+```
+
+### macOS (Intel)
+```bash
+-DSIMDJSON_IMPLEMENTATION_HASWELL=1
+```
+
+### Windows (MSVC)
+```cmd
+cl /std:c++20 /I..\include /I.. github_legacy.cpp /Fe:github_legacy_demo.exe
+```
+
+## 🐛 Troubleshooting
+
+### "reflection feature not available"
+- Ensure you're using the Bloomberg clang fork
+- Check version: `clang++ --version` should show bloomberg/clang-p2996
+
+### "SIMDJSON_STATIC_REFLECTION not working"
+- Make sure to define it before including headers:
+  ```cpp
+  #define SIMDJSON_STATIC_REFLECTION 1
+  #include <simdjson.h>
+  ```
+
+### Linking errors
+- Use single-header approach for simplicity
+- Or ensure simdjson library is properly built and linked
+
+### Performance issues
+- Add optimization flags: `-O3 -march=native`
+- Enable LTO: `-flto`
+
+## 📦 Creating a Portable Demo
+
+For conferences, prepare the demo environment:
+
+```bash
+# Install cpr library (if not available)
+# Ubuntu/Debian:
+sudo apt-get install libcpr-dev
+
+# macOS:
+brew install cpr
+
+# Or build from source:
+git clone https://github.com/libcpr/cpr.git
+cd cpr && mkdir build && cd build
+cmake .. && make && sudo make install
+
+# Create demo directory
+mkdir simdjson_oneliner_demo
+cd simdjson_oneliner_demo
+
+# Copy necessary files
+cp path/to/github_legacy.cpp .
+cp path/to/github_modern.cpp .
+cp -r path/to/simdjson/include .
+cp -r path/to/simdjson/singleheader .
+
+# Create build script
+cat > build_demo.sh << 'EOF'
+#!/bin/bash
+echo "🔨 Building Legacy Example..."
+clang++ -std=c++20 -O3 -I./include -I. \
+  github_legacy.cpp -lcpr -lcurl -o legacy_demo
+
+echo "🔨 Building Modern Example (C++26)..."  
+clang++ -std=c++26 -freflection -DSIMDJSON_STATIC_REFLECTION=1 -O3 \
+  -I./include -I. github_modern.cpp -lcpr -lcurl -o modern_demo
+
+echo "✅ Build complete!"
+echo "Run: ./legacy_demo or ./modern_demo"
+EOF
+
+chmod +x build_demo.sh
+```
+
+## 🎪 Conference Checklist
+
+- [ ] Bloomberg clang installed on demo machine
+- [ ] Both examples compile cleanly  
+- [ ] Internet connection for live API calls (or use standalone)
+- [ ] Backup: pre-recorded video of compilation and execution
+- [ ] Slides with code snippets
+- [ ] QR code for GitHub repo
+
+## 🔗 Quick Links
+
+- simdjson: https://github.com/simdjson/simdjson
+- Bloomberg Clang: https://github.com/bloomberg/clang-p2996  
+- P2996 Reflection Proposal: https://wg21.link/p2996
+- Talk Resources: [Your GitHub repo with examples]

examples/CMakeLists.txt

@@ -1 +1,23 @@
 add_subdirectory(quickstart)
+
+# Add simdjson one-liner demo examples
+if(EXISTS ${CMAKE_CURRENT_SOURCE_DIR}/github_legacy.cpp AND EXISTS ${CMAKE_CURRENT_SOURCE_DIR}/github_modern.cpp)
+    # FetchContent to download cpr
+    include(FetchContent)
+    set(CPR_ENABLE_SSL OFF CACHE BOOL "")
+    FetchContent_Declare(
+      cpr
+      GIT_REPOSITORY https://github.com/libcpr/cpr.git
+      GIT_TAG 1.10.5
+    )
+    FetchContent_MakeAvailable(cpr)
+
+    # Build the examples
+    add_executable(github_legacy github_legacy.cpp)
+    target_link_libraries(github_legacy simdjson cpr::cpr)
+
+    add_executable(github_modern github_modern.cpp)
+    target_link_libraries(github_modern simdjson cpr::cpr)
+    target_compile_options(github_modern PRIVATE -std=c++26 -freflection)
+    target_compile_definitions(github_modern PRIVATE SIMDJSON_STATIC_REFLECTION=1)
+endif()

examples/CONFERENCE_TALK.md

@@ -0,0 +1,232 @@
+# 🚀 From Boilerplate to One-Liner: The simdjson Revolution
+
+## Conference Talk: JSON Parsing in Modern C++
+
+### 📋 Talk Abstract
+Discover how simdjson's new API combined with C++26 reflection transforms JSON parsing from a tedious, error-prone task into a single line of code. This talk showcases the dramatic evolution from manual parsing to automatic struct deserialization.
+
+---
+
+## 🎯 Key Talking Points
+
+### 1. **The Problem** (2 minutes)
+- JSON is everywhere: APIs, configs, data exchange
+- C++ historically makes JSON parsing verbose
+- Show other languages: `user = json.loads(data)` in Python
+- "Why can't C++ be this simple?"
+
+### 2. **The Legacy Approach** (5 minutes)
+- Live demo: `github_legacy.cpp`
+- Walk through the boilerplate:
+  ```cpp
+  // 😓 Manual field extraction
+  user.login = std::string(doc["login"].get_string().value());
+  user.id = doc["id"].get_int64().value();
+  
+  // 😰 Handle optional fields
+  auto company_result = doc["company"];
+  if (!company_result.is_null()) {
+      user.company = std::string(company_result.get_string().value());
+  }
+  ```
+- Count the lines: ~30 lines just for parsing!
+- Error-prone: typos, missing fields, type mismatches
+
+### 3. **The Magic Moment** (3 minutes)
+- "What if I told you it could be just ONE line?"
+- Show `github_modern.cpp`
+- The magic line:
+  ```cpp
+  GitHubUser user = simdjson::from(simdjson::padded_string(json_data));
+  ```
+- Audience reaction: 🤯
+
+### 4. **How It Works** (5 minutes)
+- C++26 static reflection
+- Compile-time struct introspection
+- simdjson generates parsing code automatically
+- Zero runtime overhead - it's all compile-time!
+
+### 5. **Live Demo** (5 minutes)
+- Compile both examples
+- Run them side-by-side
+- Show identical output
+- Highlight the code difference
+- Add a new field to the struct - watch it "just work"
+
+### 6. **Deserialization Performance** (3 minutes)
+- "But is deserialization fast?"
+- Live benchmark demonstration
+- Both approaches achieve ~2.7 GB/s deserialization speed on real GitHub API data
+- Reflection adds ZERO runtime overhead to deserialization
+- "You get simplicity WITHOUT sacrificing speed!"
+- Note: We're measuring JSON → struct deserialization performance
+- Note: Performance scales with larger documents (up to 3+ GB/s)
+
+### 7. **The Future is Now** (2 minutes)
+- Bloomberg clang fork available today
+- C++26 coming soon
+- Start preparing your codebases
+- simdjson ready for the future
+
+---
+
+## 💻 Live Coding Demo Script
+
+### Setup
+```bash
+# Show the two files
+ls -la github_*.cpp
+
+# Show line count difference
+wc -l github_legacy.cpp github_modern.cpp
+```
+
+### Demo 1: The Pain of Legacy
+```bash
+# Open github_legacy.cpp in editor
+# Highlight the parse_github_user function
+# Point out each manual field extraction
+# "Look at all this code just to parse 7 fields!"
+```
+
+### Demo 2: The Modern Magic
+```bash
+# Open github_modern.cpp
+# Show the struct - "Just a plain struct!"
+# Show the one-liner
+# "That's it. That's the entire parsing code."
+```
+
+### Demo 3: Compilation and Execution
+
+**Option 1: Use the demo script (Recommended)**
+```bash
+# The script handles everything - building cpr, compiling, and running
+./conference_demo.sh
+
+# For the extended demo with serialization:
+./conference_demo_serialization.sh
+```
+
+**Option 2: Manual compilation**
+```bash
+# Build cpr first (one-time setup)
+mkdir -p ../deps && cd ../deps
+git clone https://github.com/libcpr/cpr.git
+cd cpr && git checkout 1.10.5
+mkdir build && cd build
+cmake .. -DCMAKE_CXX_COMPILER=clang++ -DCPR_USE_SYSTEM_CURL=ON \
+         -DBUILD_SHARED_LIBS=OFF -DCPR_ENABLE_SSL=OFF
+make -j4
+cd ../../../examples
+
+# Compile legacy
+clang++ -std=c++20 \
+  -I../deps/cpr/include -I../deps/cpr/build/cpr_generated_includes \
+  -I../include -I.. github_legacy.cpp ../singleheader/simdjson.cpp \
+  ../deps/cpr/build/lib/libcpr.a -lcurl -pthread -o legacy_demo
+
+# Compile modern (with reflection)
+clang++ -std=c++26 -freflection -DSIMDJSON_STATIC_REFLECTION=1 \
+  -I../deps/cpr/include -I../deps/cpr/build/cpr_generated_includes \
+  -I../include -I.. github_modern.cpp ../singleheader/simdjson.cpp \
+  ../deps/cpr/build/lib/libcpr.a -lcurl -pthread -o modern_demo
+
+# Run both - they fetch real GitHub data!
+./legacy_demo
+./modern_demo
+```
+
+### Demo 4: Adding a New Field (Crowd Pleaser!)
+```cpp
+// Add to struct in both files:
+std::string twitter_username;
+
+// Legacy: Must add parsing code
+else if (key == "twitter_username") 
+    user.twitter_username = field.value().get_string().value();
+
+// Modern: Nothing to add! It just works!
+```
+
+---
+
+## 🎤 Speaker Notes
+
+### Opening Hook
+"How many of you have written JSON parsing code in C++? Keep your hands up if you enjoyed it... Yeah, I thought so."
+
+### Transition to Modern
+"But what if I told you that in 2024, with simdjson and C++26, parsing JSON can be as simple as Python?"
+
+### After showing the one-liner
+"No, this isn't pseudocode. This is real, working C++ code. Let me prove it to you."
+
+### Addressing Skeptics
+- "It's not magic, it's metaprogramming"
+- "No runtime cost - it's all compile-time"
+- "Yes, it handles errors properly"
+- "Yes, it's production-ready"
+
+### Closing
+"The future of C++ is here. It's fast, it's simple, and it's beautiful. Stop writing boilerplate. Start writing the code that matters."
+
+---
+
+## 📊 Slide Suggestions
+
+### Slide 1: Title
+**From 50 Lines to 1: The simdjson Revolution**
+*Your Name - Conference 2024*
+
+### Slide 2: The Problem
+```python
+# Python
+user = json.loads(data)
+
+# JavaScript  
+const user = JSON.parse(data);
+
+# C++ ???
+// 😭 50+ lines of boilerplate
+```
+
+### Slide 3: The Solution
+```cpp
+// C++26 with simdjson
+GitHubUser user = simdjson::from(simdjson::padded_string(data));
+```
+
+### Slide 4: Performance Graph
+- Bar chart showing simdjson vs other parsers
+- "Fast AND Simple"
+
+### Slide 5: Timeline
+- 2018: simdjson introduced (fast but verbose)
+- 2024: New API design  
+- 2024: C++26 reflection support
+- Future: It's here!
+
+### Slide 6: Call to Action
+- Try it today: github.com/simdjson/simdjson
+- Bloomberg clang: github.com/bloomberg/clang-p2996
+- Join the revolution!
+
+---
+
+## 🔥 Audience Engagement
+
+### Interactive Elements
+1. **Live Poll**: "How many lines of code for parsing JSON?"
+2. **Challenge**: "Spot the bug in this manual parsing code"
+3. **Q&A Focus**: Performance, error handling, compatibility
+
+### Memorable Moments
+- The reveal of the one-liner
+- Live compilation with reflection
+- Adding a field without changing parsing code
+- Performance numbers
+
+### Takeaway Message
+"C++ doesn't have to be painful. With modern tools and modern standards, C++ can be as elegant as any language - and faster than all of them."

examples/INSTALL_CPR.md

@@ -0,0 +1,72 @@
+# Installing CPR Library
+
+The examples require the CPR library for making HTTP requests to the GitHub API.
+
+## Option 1: Install via Package Manager (Recommended)
+
+### Ubuntu/Debian
+```bash
+sudo apt-get update
+sudo apt-get install libcpr-dev
+```
+
+### macOS (Homebrew)
+```bash
+brew install cpr
+```
+
+### Arch Linux
+```bash
+sudo pacman -S cpr
+```
+
+## Option 2: Build from Source
+
+```bash
+# Clone cpr
+git clone https://github.com/libcpr/cpr.git
+cd cpr
+
+# Build and install
+mkdir build && cd build
+cmake .. -DCPR_USE_SYSTEM_CURL=ON
+make
+sudo make install
+```
+
+## Option 3: Using vcpkg
+
+```bash
+vcpkg install cpr
+```
+
+## Option 4: Using Conan
+
+```bash
+conan install cpr/1.10.5@
+```
+
+## Compilation
+
+Once cpr is installed, compile the examples:
+
+```bash
+# Legacy example
+clang++ -std=c++20 -I../include -I.. github_legacy.cpp -lcpr -lcurl -o github_legacy_demo
+
+# Modern example (requires Bloomberg clang)
+clang++ -std=c++26 -freflection -DSIMDJSON_STATIC_REFLECTION=1 \
+        -I../include -I.. github_modern.cpp -lcpr -lcurl -o github_modern_demo
+```
+
+## Troubleshooting
+
+If you get "cpr/cpr.h not found", check:
+- `pkg-config --cflags --libs cpr`
+- Add include path: `-I/usr/local/include`
+- Add library path: `-L/usr/local/lib`
+
+For SSL issues, ensure OpenSSL is installed:
+- Ubuntu/Debian: `sudo apt-get install libssl-dev`
+- macOS: `brew install openssl`
+- Link OpenSSL: `-lssl -lcrypto`

examples/README_ONELINER.md

@@ -0,0 +1,74 @@
+# 🚀 simdjson One-Liner Demo: From Boilerplate to Magic
+
+This demo showcases the dramatic simplification of JSON parsing in C++ using simdjson's new API combined with C++26 reflection.
+
+## Files
+
+- `github_legacy.cpp` - Traditional manual JSON parsing approach (~30 lines of parsing code)
+- `github_modern.cpp` - Modern C++26 reflection approach (1 line of parsing code!)
+- `CONFERENCE_TALK.md` - Complete conference presentation guide
+- `BUILD_INSTRUCTIONS.md` - Detailed compilation instructions
+- `conference_demo.sh` - Interactive demo script for presentations
+
+## Quick Start
+
+### Prerequisites
+- Bloomberg clang for C++26: https://github.com/bloomberg/clang-p2996
+- curl library (usually pre-installed)
+- cpr library (built automatically by demo script)
+
+### Easy Demo
+```bash
+# Just run the demo script - it handles everything!
+./conference_demo.sh
+```
+
+The script will:
+1. Build cpr if needed
+2. Compile both examples
+3. Run interactive presentation
+
+### Manual Compilation
+
+If you want to compile manually:
+
+```bash
+# Build cpr first (if not installed)
+mkdir -p ../deps && cd ../deps
+git clone https://github.com/libcpr/cpr.git
+cd cpr && git checkout 1.10.5
+mkdir build && cd build
+cmake .. -DCMAKE_CXX_COMPILER=clang++ -DCPR_USE_SYSTEM_CURL=ON -DBUILD_SHARED_LIBS=OFF -DCPR_ENABLE_SSL=OFF
+make -j4
+cd ../../../examples
+
+# Compile examples
+# Legacy
+clang++ -std=c++20 -I../deps/cpr/include -I../deps/cpr/build/cpr_generated_includes \
+        -I../include -I.. github_legacy.cpp ../singleheader/simdjson.cpp \
+        ../deps/cpr/build/lib/libcpr.a -lcurl -pthread -o legacy_demo
+
+# Modern
+clang++ -std=c++26 -freflection -DSIMDJSON_STATIC_REFLECTION=1 \
+        -I../deps/cpr/include -I../deps/cpr/build/cpr_generated_includes \
+        -I../include -I.. github_modern.cpp ../singleheader/simdjson.cpp \
+        ../deps/cpr/build/lib/libcpr.a -lcurl -pthread -o modern_demo
+```
+
+## The Magic ✨
+
+**Before (Legacy):**
+```cpp
+// 30+ lines of manual parsing...
+user.login = std::string(doc["login"].get_string().value());
+user.id = doc["id"].get_int64().value();
+// ... etc for each field
+```
+
+**After (Modern):**
+```cpp
+// Just ONE line!
+GitHubUser user = simdjson::from(simdjson::padded_string(response.text));
+```
+
+Both examples fetch real data from GitHub API to demonstrate real-world usage!

examples/SERIALIZATION_README.md

@@ -0,0 +1,53 @@
+# simdjson Serialization with C++26 Reflection
+
+This directory now includes examples demonstrating **both** deserialization and serialization using C++26 reflection features.
+
+## 🚀 Quick Start
+
+### Basic Round-Trip Demo
+```bash
+# Compile and run the simple round-trip demo
+clang++ -std=c++26 -freflection -DSIMDJSON_STATIC_REFLECTION=1 \
+    reflection_roundtrip_demo.cpp ../singleheader/simdjson.cpp \
+    -o reflection_roundtrip_demo
+./reflection_roundtrip_demo
+```
+
+### Conference Demo with Serialization
+```bash
+# Run the extended conference demo that includes serialization
+./conference_demo_serialization.sh
+```
+
+## 📝 What's New?
+
+The experimental `simdjson::builder::to_json_string()` function enables one-line serialization:
+
+```cpp
+// Deserialize JSON → Struct
+MyStruct obj = simdjson::from(json);
+
+// Serialize Struct → JSON (NEW!)
+std::string json = simdjson::builder::to_json_string(obj);
+```
+
+## 🎯 Features
+
+- **Zero boilerplate**: No need to write serialization code
+- **Automatic handling**: Optional fields, containers, nested structures
+- **Type-safe**: Compile-time checking with reflection
+- **Performant**: Optimized string building
+
+## ⚠️ Requirements
+
+- Bloomberg's clang fork (clang-p2996) with C++26 reflection support
+- Build with `-DSIMDJSON_STATIC_REFLECTION=1`
+- Include `simdjson/builder/json_builder.h`
+
+## 📊 Performance
+
+While serialization is generally slower than deserialization (due to string building vs parsing), the reflection-based approach is still highly optimized and significantly faster than manual string concatenation approaches.
+
+## 🔧 Status
+
+This serialization support is **experimental** and part of the builder API. The API may change as C++26 reflection features evolve.

examples/conference_demo.sh

@@ -0,0 +1,167 @@
+#!/bin/bash
+# Conference Demo Script - simdjson One-Liner Magic
+# Run this during your talk for a smooth demo experience
+
+# Check if cpr is built
+if [ ! -f "../deps/cpr/build/lib/libcpr.a" ]; then
+    echo "⚠️  CPR library not found. Building it first..."
+    echo ""
+    if [ ! -d "../deps/cpr" ]; then
+        mkdir -p ../deps
+        cd ../deps
+        git clone https://github.com/libcpr/cpr.git
+        cd cpr && git checkout 1.10.5
+        cd ../..
+    fi
+    cd ../deps/cpr
+    mkdir -p build && cd build
+    cmake .. -DCMAKE_CXX_COMPILER=clang++ -DCPR_USE_SYSTEM_CURL=ON -DBUILD_SHARED_LIBS=OFF -DCPR_ENABLE_SSL=OFF
+    make -j4
+    cd ../../../examples
+    echo "✅ CPR built successfully!"
+    echo ""
+fi
+
+clear
+echo "🚀 simdjson: From Boilerplate to One-Liner"
+echo "==========================================="
+echo ""
+echo "Press Enter to continue..."
+read
+
+# Show the legacy approach
+echo "📚 First, let's look at the LEGACY approach..."
+echo ""
+echo "Opening github_legacy.cpp..."
+sleep 1
+echo ""
+echo "Key points:"
+echo "  • Manual parse_github_user() function"
+echo "  • Extract each field individually"
+echo "  • Handle optional fields explicitly"
+echo "  • ~30 lines of parsing code"
+echo ""
+echo "Press Enter to see the code..."
+read
+
+# Display key parts of legacy code
+cat github_legacy.cpp | grep -A 20 "parse_github_user" | head -25
+
+echo ""
+echo "😓 That's a lot of boilerplate!"
+echo ""
+echo "Press Enter to compile and run..."
+read
+
+# Compile legacy
+echo "🔨 Compiling legacy version..."
+echo "Command: clang++ -std=c++20 -I../deps/cpr/include -I../deps/cpr/build/cpr_generated_includes -I../include -I.. github_legacy.cpp ../singleheader/simdjson.cpp ../deps/cpr/build/lib/libcpr.a -lcurl -pthread -o legacy_demo"
+clang++ -std=c++20 -I../deps/cpr/include -I../deps/cpr/build/cpr_generated_includes -I../include -I.. github_legacy.cpp ../singleheader/simdjson.cpp ../deps/cpr/build/lib/libcpr.a -lcurl -pthread -o legacy_demo
+echo "✅ Compiled!"
+echo ""
+echo "🏃 Running legacy demo (fetching real GitHub data)..."
+echo ""
+./legacy_demo
+
+echo ""
+echo "Press Enter to see the MODERN approach..."
+read
+
+clear
+echo "✨ Now, let's look at the MODERN approach with C++26 reflection..."
+echo ""
+echo "Opening github_modern.cpp..."
+sleep 1
+echo ""
+echo "Key points:"
+echo "  • Just declare your struct"
+echo "  • ONE line of parsing code"
+echo "  • C++26 reflection handles everything"
+echo "  • No manual field extraction!"
+echo ""
+echo "Press Enter to see the magic..."
+read
+
+# Show the struct and the one-liner
+echo "The struct (just a plain struct!):"
+echo ""
+cat github_modern.cpp | grep -A 10 "struct GitHubUser" | head -12
+echo ""
+echo "The parsing code (ONE LINE!):"
+echo ""
+echo "    GitHubUser user = simdjson::from(simdjson::padded_string(response.text));"
+echo ""
+echo "🤯 That's it! That's all the parsing code!"
+echo ""
+echo "Press Enter to compile with C++26 reflection..."
+read
+
+# Compile modern
+echo "🔨 Compiling modern version with Bloomberg clang..."
+echo "Command: clang++ -std=c++26 -freflection -DSIMDJSON_STATIC_REFLECTION=1 -I../deps/cpr/include -I../deps/cpr/build/cpr_generated_includes -I../include -I.. github_modern.cpp ../singleheader/simdjson.cpp ../deps/cpr/build/lib/libcpr.a -lcurl -pthread -o modern_demo"
+clang++ -std=c++26 -freflection -DSIMDJSON_STATIC_REFLECTION=1 -I../deps/cpr/include -I../deps/cpr/build/cpr_generated_includes -I../include -I.. github_modern.cpp ../singleheader/simdjson.cpp ../deps/cpr/build/lib/libcpr.a -lcurl -pthread -o modern_demo
+echo "✅ Compiled!"
+echo ""
+echo "🏃 Running modern demo (fetching real GitHub data)..."
+echo ""
+./modern_demo
+
+echo ""
+echo "Press Enter to see side-by-side comparison..."
+read
+
+clear
+echo "📊 SIDE-BY-SIDE COMPARISON"
+echo "========================="
+echo ""
+echo "Legacy Approach:                    Modern Approach (C++26):"
+echo "----------------                    ------------------------"
+echo "❌ 30+ lines of parsing code        ✅ 1 line of parsing code"
+echo "❌ Manual field extraction          ✅ Automatic with reflection"
+echo "❌ Error-prone                      ✅ Type-safe"
+echo "❌ Hard to maintain                 ✅ Just update the struct"
+echo "❌ Boilerplate for each type        ✅ Works for any struct"
+echo ""
+echo ""
+echo "Press Enter to run PERFORMANCE BENCHMARKS..."
+read
+
+clear
+echo "⚡ DESERIALIZATION PERFORMANCE BENCHMARKS"
+echo "========================================"
+echo ""
+echo "Let's measure the actual JSON → struct deserialization speed..."
+echo ""
+
+# Compile benchmarks if not exist
+if [ ! -f "./legacy_benchmark" ] || [ ! -f "./modern_benchmark" ]; then
+    echo "🔨 Compiling benchmark versions..."
+    
+    clang++ -std=c++20 -O3 -march=native \
+      -I../deps/cpr/include -I../deps/cpr/build/cpr_generated_includes \
+      -I../include -I.. github_legacy_benchmark.cpp ../singleheader/simdjson.cpp \
+      ../deps/cpr/build/lib/libcpr.a -lcurl -pthread -o legacy_benchmark 2>/dev/null
+    
+    clang++ -std=c++26 -freflection -O3 -march=native \
+      -DSIMDJSON_STATIC_REFLECTION=1 \
+      -I../deps/cpr/include -I../deps/cpr/build/cpr_generated_includes \
+      -I../include -I.. github_modern_benchmark.cpp ../singleheader/simdjson.cpp \
+      ../deps/cpr/build/lib/libcpr.a -lcurl -pthread -o modern_benchmark 2>/dev/null
+fi
+
+echo "🏃 Running legacy benchmark..."
+echo ""
+./legacy_benchmark
+
+echo ""
+echo "Press Enter to run modern benchmark..."
+read
+
+echo "🏃 Running modern benchmark..."
+echo ""
+./modern_benchmark
+
+echo ""
+echo "🎉 The future of C++ is here!"
+echo ""
+echo "Questions?"

examples/conference_demo_serialization.sh

@@ -0,0 +1,322 @@
+#!/bin/bash
+# Conference Demo Script - simdjson One-Liner Magic (WITH SERIALIZATION!)
+# Extended demo showcasing both deserialization AND serialization with C++26 reflection
+
+# Check if cpr is built
+if [ ! -f "../deps/cpr/build/lib/libcpr.a" ]; then
+    echo "⚠️  CPR library not found. Building it first..."
+    echo ""
+    if [ ! -d "../deps/cpr" ]; then
+        mkdir -p ../deps
+        cd ../deps
+        git clone https://github.com/libcpr/cpr.git
+        cd cpr && git checkout 1.10.5
+        cd ../..
+    fi
+    cd ../deps/cpr
+    mkdir -p build && cd build
+    cmake .. -DCMAKE_CXX_COMPILER=clang++ -DCPR_USE_SYSTEM_CURL=ON -DBUILD_SHARED_LIBS=OFF -DCPR_ENABLE_SSL=OFF
+    make -j4
+    cd ../../../examples
+    echo "✅ CPR built successfully!"
+    echo ""
+fi
+
+clear
+echo "🚀 simdjson: Complete JSON Round-Trip with C++26 Reflection"
+echo "============================================================"
+echo ""
+echo "Today we'll showcase BOTH deserialization AND serialization!"
+echo ""
+echo "Press Enter to continue..."
+read
+
+# Create a demo program that shows serialization
+cat > github_serialization_demo.cpp << 'EOF'
+#include <iostream>
+#include <iomanip>
+#include "simdjson.h"
+#include <cpr/cpr.h>
+
+struct GitHubUser {
+    std::string login;
+    std::optional<std::string> name;
+    std::optional<std::string> company;
+    std::optional<std::string> blog;
+    std::optional<std::string> location;
+    std::optional<std::string> email;
+    std::optional<std::string> bio;
+    int64_t public_repos;
+    int64_t followers;
+    int64_t following;
+};
+
+int main() {
+    std::cout << "🔄 C++26 Reflection: Complete JSON Round-Trip Demo\n";
+    std::cout << "================================================\n\n";
+    
+    // Step 1: Fetch real data from GitHub
+    std::cout << "📡 Fetching GitHub user data...\n";
+    auto response = cpr::Get(cpr::Url{"https://api.github.com/users/simdjson"});
+    
+    if (response.status_code != 200) {
+        std::cerr << "Error: Failed to fetch data\n";
+        return 1;
+    }
+    
+    std::cout << "✅ Received " << response.text.length() << " bytes of JSON\n\n";
+    
+    // Step 2: Deserialize with ONE LINE
+    std::cout << "📥 DESERIALIZATION (JSON → Struct)\n";
+    std::cout << "Code: GitHubUser user = simdjson::from(simdjson::padded_string(response.text));\n\n";
+    
+    GitHubUser user = simdjson::from(simdjson::padded_string(response.text));
+    
+    // Show the data we parsed
+    std::cout << "Parsed data:\n";
+    std::cout << "  • Login: " << user.login << "\n";
+    std::cout << "  • Name: " << (user.name.has_value() ? *user.name : "<not set>") << "\n";
+    std::cout << "  • Company: " << (user.company.has_value() ? *user.company : "<not set>") << "\n";
+    std::cout << "  • Location: " << (user.location.has_value() ? *user.location : "<not set>") << "\n";
+    std::cout << "  • Bio: " << (user.bio.has_value() ? *user.bio : "<not set>") << "\n";
+    std::cout << "  • Repos: " << user.public_repos << "\n";
+    std::cout << "  • Followers: " << user.followers << "\n\n";
+    
+    // Step 3: Modify the data
+    std::cout << "✏️  Modifying data...\n";
+    user.followers += 1000;  // Wishful thinking!
+    user.name = "simdjson - JSON at the speed of light";  // Set a name
+    user.bio = user.bio.value_or("") + " (Now with C++26 reflection!)";
+    std::cout << "  • Added 1000 followers (we can dream!)\n";
+    std::cout << "  • Set organization name\n";
+    std::cout << "  • Updated bio\n\n";
+    
+    // Step 4: Serialize back to JSON with ONE LINE
+    std::cout << "📤 SERIALIZATION (Struct → JSON)\n";
+    std::cout << "Code: std::string json = simdjson::builder::to_json_string(user);\n\n";
+    
+    auto json_result = simdjson::builder::to_json_string(user);
+    if (json_result.error()) {
+        std::cerr << "Serialization error!\n";
+        return 1;
+    }
+    std::string json = json_result.value();
+    
+    std::cout << "Generated JSON (" << json.length() << " bytes):\n";
+    // Pretty print first 200 chars
+    if (json.length() > 200) {
+        std::cout << json.substr(0, 200) << "...\n\n";
+    } else {
+        std::cout << json << "\n\n";
+    }
+    
+    // Step 5: Verify round-trip
+    std::cout << "🔄 ROUND-TRIP VERIFICATION\n";
+    std::cout << "Parsing our generated JSON back...\n";
+    
+    GitHubUser user2 = simdjson::from(simdjson::padded_string(json));
+    
+    std::cout << "✅ Round-trip successful!\n";
+    std::cout << "  • Original followers: " << user.followers << "\n";
+    std::cout << "  • Parsed followers: " << user2.followers << "\n";
+    std::cout << "  • Name set correctly: " << (user2.name.has_value() && *user2.name == *user.name ? "YES" : "NO") << "\n";
+    std::cout << "  • Bio preserved: " << (user2.bio.has_value() ? "YES" : "NO") << "\n\n";
+    
+    std::cout << "🎉 That's it! Two lines of code for complete JSON handling:\n";
+    std::cout << "   • Deserialization: simdjson::from(...)\n";
+    std::cout << "   • Serialization: simdjson::builder::to_json_string(...)\n";
+    
+    return 0;
+}
+EOF
+
+# Create a benchmark that includes serialization
+cat > serialization_benchmark.cpp << 'EOF'
+#include <iostream>
+#include <iomanip>
+#include <chrono>
+#include "simdjson.h"
+#include <map>
+
+struct TestData {
+    std::string name;
+    std::vector<int> numbers;
+    std::map<std::string, double> metrics;
+    bool active;
+    std::optional<std::string> description;
+};
+
+int main() {
+    std::cout << "⚡ Serialization Performance Benchmark\n";
+    std::cout << "=====================================\n\n";
+    
+    // Create test data
+    TestData data{
+        .name = "Performance Test",
+        .numbers = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10},
+        .metrics = {{"latency", 1.23}, {"throughput", 456.78}, {"cpu", 89.01}},
+        .active = true,
+        .description = "Testing reflection-based serialization performance"
+    };
+    
+    const int iterations = 100000;
+    
+    // Benchmark serialization
+    std::cout << "📤 Benchmarking serialization (" << iterations << " iterations)...\n";
+    
+    auto start = std::chrono::high_resolution_clock::now();
+    
+    std::string json;
+    for (int i = 0; i < iterations; i++) {
+        auto result = simdjson::builder::to_json_string(data);
+        if (i == 0 && !result.error()) {
+            json = result.value();
+        }
+    }
+    
+    auto end = std::chrono::high_resolution_clock::now();
+    auto duration = std::chrono::duration_cast<std::chrono::microseconds>(end - start);
+    
+    std::cout << "\nResults:\n";
+    std::cout << "  • Generated JSON size: " << json.length() << " bytes\n";
+    std::cout << "  • Total time: " << duration.count() / 1000.0 << " ms\n";
+    
+    double time_per_iteration_us = duration.count() / double(iterations);
+    double time_per_iteration_s = time_per_iteration_us / 1000000.0;
+    double bytes_per_second = json.length() / time_per_iteration_s;
+    double mb_per_second = bytes_per_second / (1024.0 * 1024.0);
+    
+    std::cout << "  • Time per serialization: " << std::fixed << std::setprecision(2) << time_per_iteration_us << " μs\n";
+    std::cout << "  • Throughput: " << std::fixed << std::setprecision(2) << mb_per_second << " MB/s\n";
+    
+    std::cout << "\nGenerated JSON:\n" << json << "\n\n";
+    
+    // Benchmark deserialization for comparison
+    std::cout << "📥 Benchmarking deserialization (for comparison)...\n";
+    
+    simdjson::padded_string padded_json(json);
+    start = std::chrono::high_resolution_clock::now();
+    
+    for (int i = 0; i < iterations; i++) {
+        TestData parsed = simdjson::from(padded_json);
+    }
+    
+    end = std::chrono::high_resolution_clock::now();
+    duration = std::chrono::duration_cast<std::chrono::microseconds>(end - start);
+    
+    std::cout << "\nResults:\n";
+    time_per_iteration_us = duration.count() / double(iterations);
+    time_per_iteration_s = time_per_iteration_us / 1000000.0;
+    bytes_per_second = json.length() / time_per_iteration_s;
+    mb_per_second = bytes_per_second / (1024.0 * 1024.0);
+    
+    std::cout << "  • Time per deserialization: " << std::fixed << std::setprecision(2) << time_per_iteration_us << " μs\n";
+    std::cout << "  • Throughput: " << std::fixed << std::setprecision(2) << mb_per_second << " MB/s\n";
+    
+    std::cout << "\n✅ Both serialization and deserialization work with reflection!\n";
+    
+    return 0;
+}
+EOF
+
+echo "📝 First, let's see the traditional approach to serialization..."
+echo ""
+echo "Press Enter to see manual serialization code..."
+read
+
+cat > manual_serialization_example.cpp << 'EOF'
+// The OLD way - Manual serialization
+std::string serialize_github_user(const GitHubUser& user) {
+    std::string json = "{";
+    json += "\"login\":\"" + user.login + "\",";
+    json += "\"name\":\"" + user.name + "\",";
+    json += "\"company\":\"" + user.company + "\",";
+    json += "\"blog\":\"" + user.blog + "\",";
+    json += "\"location\":\"" + user.location + "\",";
+    
+    if (user.email.has_value()) {
+        json += "\"email\":\"" + *user.email + "\",";
+    }
+    if (user.bio.has_value()) {
+        json += "\"bio\":\"" + *user.bio + "\",";
+    }
+    
+    json += "\"public_repos\":" + std::to_string(user.public_repos) + ",";
+    json += "\"followers\":" + std::to_string(user.followers) + ",";
+    json += "\"following\":" + std::to_string(user.following);
+    json += "}";
+    
+    return json;
+}
+EOF
+
+cat manual_serialization_example.cpp
+echo ""
+echo "😓 That's error-prone and doesn't handle escaping!"
+echo ""
+echo "Press Enter to see the MODERN approach..."
+read
+
+clear
+echo "✨ The MODERN approach with C++26 reflection:"
+echo ""
+echo "Deserialization:"
+echo "    GitHubUser user = simdjson::from(json);"
+echo ""
+echo "Serialization:"
+echo "    std::string json = simdjson::builder::to_json_string(user);"
+echo ""
+echo "🤯 That's it! Bidirectional JSON handling in TWO lines!"
+echo ""
+echo "Press Enter to compile and run the complete demo..."
+read
+
+# Compile and run serialization demo
+echo "🔨 Compiling serialization demo..."
+clang++ -std=c++26 -freflection -DSIMDJSON_STATIC_REFLECTION=1 \
+    -I../deps/cpr/include -I../deps/cpr/build/cpr_generated_includes \
+    -I../include -I.. github_serialization_demo.cpp ../singleheader/simdjson.cpp \
+    ../deps/cpr/build/lib/libcpr.a -lcurl -pthread -o serialization_demo
+
+echo "✅ Compiled!"
+echo ""
+echo "🏃 Running complete round-trip demo..."
+echo ""
+./serialization_demo
+
+echo ""
+echo "Press Enter to run performance benchmarks..."
+read
+
+clear
+echo "⚡ PERFORMANCE BENCHMARKS"
+echo "========================"
+echo ""
+
+# Compile benchmark
+echo "🔨 Compiling performance benchmark..."
+clang++ -std=c++26 -freflection -O3 -march=native \
+    -DSIMDJSON_STATIC_REFLECTION=1 \
+    -I../include -I.. serialization_benchmark.cpp ../singleheader/simdjson.cpp \
+    -pthread -o serialization_benchmark
+
+echo "✅ Compiled!"
+echo ""
+echo "🏃 Running benchmark..."
+echo ""
+./serialization_benchmark
+
+echo ""
+echo "🎉 Summary:"
+echo "==========="
+echo "• ONE line for deserialization"
+echo "• ONE line for serialization"
+echo "• Works with complex nested structures"
+echo "• Handles optional fields automatically"
+echo "• Type-safe and performant"
+echo "• No manual parsing/building code needed!"
+echo ""
+echo "The future of C++ JSON handling is here! 🚀"
+
+# Cleanup
+rm -f manual_serialization_example.cpp

examples/github_legacy.cpp

@@ -0,0 +1,83 @@
+// Legacy approach - manual JSON parsing with simdjson
+#include <simdjson.h>
+#include <cpr/cpr.h>
+#include <iostream>
+#include <string>
+#include <optional>
+
+struct GitHubUser {
+    std::string login;
+    int64_t id;
+    std::string name;
+    std::optional<std::string> company;
+    std::optional<std::string> location;
+    int64_t public_repos;
+    int64_t followers;
+};
+
+// Legacy approach - manual parsing with lots of boilerplate
+GitHubUser parse_github_user(const std::string& json_str) {
+    GitHubUser user;
+    
+    simdjson::ondemand::parser parser;
+    simdjson::padded_string json(json_str);
+    simdjson::ondemand::document doc = parser.iterate(json);
+    
+    // Manual field extraction with error checking
+    user.login = std::string(doc["login"].get_string().value());
+    user.id = doc["id"].get_int64().value();
+    user.name = std::string(doc["name"].get_string().value());
+    
+    // Handle optional fields
+    auto company_result = doc["company"];
+    if (!company_result.is_null()) {
+        user.company = std::string(company_result.get_string().value());
+    }
+    
+    auto location_result = doc["location"];
+    if (!location_result.is_null()) {
+        user.location = std::string(location_result.get_string().value());
+    }
+    
+    user.public_repos = doc["public_repos"].get_int64().value();
+    user.followers = doc["followers"].get_int64().value();
+    
+    return user;
+}
+
+int main() {
+    std::cout << "📚 Legacy Approach - Manual JSON Parsing\n";
+    std::cout << "========================================\n\n";
+    
+    // Fetch data from GitHub API
+    auto response = cpr::Get(
+        cpr::Url{"https://api.github.com/users/lemire"},
+        cpr::Header{{"User-Agent", "simdjson-legacy-demo"}}
+    );
+    
+    if (response.status_code != 200) {
+        std::cerr << "❌ Failed to fetch data: HTTP " << response.status_code << "\n";
+        return 1;
+    }
+    
+    try {
+        // 😓 The old way - manual parsing with lots of code
+        GitHubUser user = parse_github_user(response.text);
+        
+        // Display results
+        std::cout << "GitHub User: " << user.name << " (@" << user.login << ")\n";
+        std::cout << "ID: " << user.id << "\n";
+        if (user.company) std::cout << "Company: " << *user.company << "\n";
+        if (user.location) std::cout << "Location: " << *user.location << "\n";
+        std::cout << "Public Repos: " << user.public_repos << "\n";
+        std::cout << "Followers: " << user.followers << "\n";
+        
+        std::cout << "\n⚠️  Notice all the manual parsing code required!\n";
+        
+    } catch (const simdjson::simdjson_error& e) {
+        std::cerr << "❌ Parsing error: " << e.what() << "\n";
+        return 1;
+    }
+    
+    return 0;
+}

examples/github_legacy_benchmark.cpp

@@ -0,0 +1,165 @@
+// Legacy approach with performance measurement
+#include <simdjson.h>
+#include <cpr/cpr.h>
+#include <iostream>
+#include <string>
+#include <optional>
+#include <chrono>
+#include <iomanip>
+#include <sstream>
+
+struct GitHubUser {
+    std::string login;
+    int64_t id;
+    std::string name;
+    std::optional<std::string> company;
+    std::optional<std::string> location;
+    int64_t public_repos;
+    int64_t followers;
+};
+
+// Manual parsing function (the old way)
+GitHubUser parse_github_user(const std::string& json_str) {
+    GitHubUser user;
+    
+    simdjson::ondemand::parser parser;
+    simdjson::padded_string json(json_str);
+    simdjson::ondemand::document doc = parser.iterate(json);
+    
+    // Manual field extraction with error checking
+    user.login = std::string(doc["login"].get_string().value());
+    user.id = doc["id"].get_int64().value();
+    user.name = std::string(doc["name"].get_string().value());
+    
+    // Handle optional fields
+    auto company_result = doc["company"];
+    if (!company_result.is_null()) {
+        user.company = std::string(company_result.get_string().value());
+    }
+    
+    auto location_result = doc["location"];
+    if (!location_result.is_null()) {
+        user.location = std::string(location_result.get_string().value());
+    }
+    
+    user.public_repos = doc["public_repos"].get_int64().value();
+    user.followers = doc["followers"].get_int64().value();
+    
+    return user;
+}
+
+// Manual serialization function (the old way)
+std::string serialize_github_user(const GitHubUser& user) {
+    std::ostringstream json;
+    json << "{";
+    json << "\"login\":\"" << user.login << "\",";
+    json << "\"id\":" << user.id << ",";
+    json << "\"name\":\"" << user.name << "\",";
+    
+    if (user.company.has_value()) {
+        json << "\"company\":\"" << *user.company << "\",";
+    } else {
+        json << "\"company\":null,";
+    }
+    
+    if (user.location.has_value()) {
+        json << "\"location\":\"" << *user.location << "\",";
+    } else {
+        json << "\"location\":null,";
+    }
+    
+    json << "\"public_repos\":" << user.public_repos << ",";
+    json << "\"followers\":" << user.followers;
+    json << "}";
+    
+    return json.str();
+}
+
+int main() {
+    std::cout << "📚 Legacy Approach - Deserialization Performance Benchmark\n";
+    std::cout << "=========================================================\n\n";
+    
+    // Fetch data from GitHub API
+    auto response = cpr::Get(
+        cpr::Url{"https://api.github.com/users/lemire"},
+        cpr::Header{{"User-Agent", "simdjson-benchmark"}}
+    );
+    
+    if (response.status_code != 200) {
+        std::cerr << "❌ Failed to fetch data: HTTP " << response.status_code << "\n";
+        return 1;
+    }
+    
+    // Warm up
+    for (int i = 0; i < 100; ++i) {
+        auto user = parse_github_user(response.text);
+    }
+    
+    // Benchmark
+    const int iterations = 10000;
+    auto start = std::chrono::high_resolution_clock::now();
+    
+    for (int i = 0; i < iterations; ++i) {
+        auto user = parse_github_user(response.text);
+        // Prevent optimization
+        if (i == 0) {
+            std::cout << "Parsing: " << user.name << " (@" << user.login << ")\n\n";
+        }
+    }
+    
+    auto end = std::chrono::high_resolution_clock::now();
+    auto duration = std::chrono::duration_cast<std::chrono::microseconds>(end - start);
+    
+    // Calculate performance metrics
+    double time_per_parse = duration.count() / static_cast<double>(iterations);
+    double bytes_per_parse = response.text.size();
+    double gb_per_second = (bytes_per_parse * iterations) / (duration.count() * 1000.0);
+    
+    std::cout << "📊 Deserialization Performance Results:\n";
+    std::cout << "  • JSON size: " << bytes_per_parse << " bytes\n";
+    std::cout << "  • Iterations: " << iterations << "\n";
+    std::cout << "  • Total time: " << duration.count() / 1000.0 << " ms\n";
+    std::cout << "  • Time per deserialization: " << std::fixed << std::setprecision(2) << time_per_parse << " μs\n";
+    std::cout << "  • Deserialization speed: " << std::fixed << std::setprecision(2) << gb_per_second << " GB/s\n";
+    
+    // Now benchmark serialization
+    std::cout << "\n📝 Serialization Performance Benchmark\n";
+    std::cout << "=====================================\n\n";
+    
+    // Parse once to get a user object
+    auto user = parse_github_user(response.text);
+    
+    // Warm up serialization
+    for (int i = 0; i < 100; ++i) {
+        auto json_str = serialize_github_user(user);
+    }
+    
+    // Benchmark serialization
+    start = std::chrono::high_resolution_clock::now();
+    
+    for (int i = 0; i < iterations; ++i) {
+        auto json_str = serialize_github_user(user);
+        // Prevent optimization
+        if (i == 0) {
+            std::cout << "Serialized JSON size: " << json_str.length() << " bytes\n\n";
+        }
+    }
+    
+    end = std::chrono::high_resolution_clock::now();
+    duration = std::chrono::duration_cast<std::chrono::microseconds>(end - start);
+    
+    // Calculate serialization performance metrics
+    time_per_parse = duration.count() / static_cast<double>(iterations);
+    double serialized_size = serialize_github_user(user).length();
+    gb_per_second = (serialized_size * iterations) / (duration.count() * 1000.0);
+    
+    std::cout << "📊 Serialization Performance Results:\n";
+    std::cout << "  • JSON size: " << serialized_size << " bytes\n";
+    std::cout << "  • Iterations: " << iterations << "\n";
+    std::cout << "  • Total time: " << duration.count() / 1000.0 << " ms\n";
+    std::cout << "  • Time per serialization: " << std::fixed << std::setprecision(2) << time_per_parse << " μs\n";
+    std::cout << "  • Serialization speed: " << std::fixed << std::setprecision(2) << gb_per_second << " GB/s\n";
+    std::cout << "\n⚠️  Note: Manual serialization with string concatenation\n";
+    
+    return 0;
+}

examples/github_modern.cpp

@@ -0,0 +1,61 @@
+// Modern approach - C++26 reflection with simdjson
+// Compile with Bloomberg clang fork:
+// clang++ -std=c++26 -freflection -DSIMDJSON_STATIC_REFLECTION=1 ...
+#include <simdjson.h>
+#include <simdjson/convert.h>
+#include <cpr/cpr.h>
+#include <iostream>
+#include <string>
+#include <optional>
+
+// 🎯 JUST DECLARE YOUR STRUCT - THAT'S IT!
+// No serialization code needed with C++26 reflection
+struct GitHubUser {
+    std::string login;
+    int64_t id;
+    std::string name;
+    std::optional<std::string> company;
+    std::optional<std::string> location;
+    int64_t public_repos;
+    int64_t followers;
+};
+// NO BOILERPLATE CODE NEEDED! 🎉
+
+int main() {
+    std::cout << "✨ Modern Approach - C++26 Reflection\n";
+    std::cout << "=====================================\n\n";
+    
+    // Fetch data from GitHub API
+    auto response = cpr::Get(
+        cpr::Url{"https://api.github.com/users/lemire"},
+        cpr::Header{{"User-Agent", "simdjson-modern-demo"}}
+    );
+    
+    if (response.status_code != 200) {
+        std::cerr << "❌ Failed to fetch data: HTTP " << response.status_code << "\n";
+        return 1;
+    }
+    
+    try {
+        // ✨ THE MAGIC - Just one line, no boilerplate!
+        // C++26 reflection handles everything automatically
+        GitHubUser user = simdjson::from(simdjson::padded_string(response.text));
+        
+        // Display results
+        std::cout << "GitHub User: " << user.name << " (@" << user.login << ")\n";
+        std::cout << "ID: " << user.id << "\n";
+        if (user.company) std::cout << "Company: " << *user.company << "\n";
+        if (user.location) std::cout << "Location: " << *user.location << "\n";
+        std::cout << "Public Repos: " << user.public_repos << "\n";
+        std::cout << "Followers: " << user.followers << "\n";
+        
+        std::cout << "\n🚀 That's it! No manual parsing code needed!\n";
+        std::cout << "   C++26 reflection generates everything automatically.\n";
+        
+    } catch (const simdjson::simdjson_error& e) {
+        std::cerr << "❌ Parsing error: " << e.what() << "\n";
+        return 1;
+    }
+    
+    return 0;
+}

examples/github_modern_benchmark.cpp

@@ -0,0 +1,86 @@
+// Modern approach with performance measurement - C++26 reflection
+#include <simdjson.h>
+#include <simdjson/convert.h>
+#include <cpr/cpr.h>
+#include <iostream>
+#include <string>
+#include <optional>
+#include <chrono>
+#include <iomanip>
+#include <sstream>
+
+// Just declare your struct - reflection handles the rest!
+struct GitHubUser {
+    std::string login;
+    int64_t id;
+    std::string name;
+    std::optional<std::string> company;
+    std::optional<std::string> location;
+    int64_t public_repos;
+    int64_t followers;
+};
+
+int main() {
+    std::cout << "✨ Modern Approach - Deserialization Performance Benchmark (C++26)\n";
+    std::cout << "================================================================\n\n";
+    
+    // Fetch data from GitHub API
+    auto response = cpr::Get(
+        cpr::Url{"https://api.github.com/users/lemire"},
+        cpr::Header{{"User-Agent", "simdjson-benchmark"}}
+    );
+    
+    if (response.status_code != 200) {
+        std::cerr << "❌ Failed to fetch data: HTTP " << response.status_code << "\n";
+        return 1;
+    }
+    
+    // Warm up
+    for (int i = 0; i < 100; ++i) {
+        GitHubUser user = simdjson::from(simdjson::padded_string(response.text));
+    }
+    
+    // Benchmark
+    const int iterations = 10000;
+    auto start = std::chrono::high_resolution_clock::now();
+    
+    for (int i = 0; i < iterations; ++i) {
+        GitHubUser user = simdjson::from(simdjson::padded_string(response.text));
+        // Prevent optimization
+        if (i == 0) {
+            std::cout << "Parsing: " << user.name << " (@" << user.login << ")\n\n";
+        }
+    }
+    
+    auto end = std::chrono::high_resolution_clock::now();
+    auto duration = std::chrono::duration_cast<std::chrono::microseconds>(end - start);
+    
+    // Calculate performance metrics
+    double time_per_parse = duration.count() / static_cast<double>(iterations);
+    double bytes_per_parse = response.text.size();
+    double gb_per_second = (bytes_per_parse * iterations) / (duration.count() * 1000.0);
+    
+    std::cout << "📊 Deserialization Performance Results:\n";
+    std::cout << "  • JSON size: " << bytes_per_parse << " bytes\n";
+    std::cout << "  • Iterations: " << iterations << "\n";
+    std::cout << "  • Total time: " << duration.count() / 1000.0 << " ms\n";
+    std::cout << "  • Time per deserialization: " << std::fixed << std::setprecision(2) << time_per_parse << " μs\n";
+    std::cout << "  • Deserialization speed: " << std::fixed << std::setprecision(2) << gb_per_second << " GB/s\n";
+    
+    std::cout << "\n🚀 Same performance, just ONE line of deserialization code!\n";
+    
+    // Serialization note
+    std::cout << "\n📝 Serialization with Reflection\n";
+    std::cout << "================================\n\n";
+    std::cout << "⚠️  NOTE: simdjson doesn't yet support reflection-based serialization.\n";
+    std::cout << "   The `simdjson::to` function is not yet implemented.\n";
+    std::cout << "   This is a future enhancement that would provide:\n";
+    std::cout << "   • One-line serialization: simdjson::to<std::string>(user)\n";
+    std::cout << "   • Automatic JSON generation from C++ structs\n";
+    std::cout << "   • No manual string building required\n";
+    std::cout << "\n";
+    std::cout << "   For now, serialization still requires manual implementation,\n";
+    std::cout << "   but deserialization is fully automated with reflection! 🎉\n";
+    
+    return 0;
+}

examples/github_serialization_demo.cpp

@@ -0,0 +1,95 @@
+#include <iostream>
+#include <iomanip>
+#include "simdjson.h"
+#include <cpr/cpr.h>
+
+struct GitHubUser {
+    std::string login;
+    std::optional<std::string> name;
+    std::optional<std::string> company;
+    std::optional<std::string> blog;
+    std::optional<std::string> location;
+    std::optional<std::string> email;
+    std::optional<std::string> bio;
+    int64_t public_repos;
+    int64_t followers;
+    int64_t following;
+};
+
+int main() {
+    std::cout << "🔄 C++26 Reflection: Complete JSON Round-Trip Demo\n";
+    std::cout << "================================================\n\n";
+    
+    // Step 1: Fetch real data from GitHub
+    std::cout << "📡 Fetching GitHub user data...\n";
+    auto response = cpr::Get(cpr::Url{"https://api.github.com/users/simdjson"});
+    
+    if (response.status_code != 200) {
+        std::cerr << "Error: Failed to fetch data\n";
+        return 1;
+    }
+    
+    std::cout << "✅ Received " << response.text.length() << " bytes of JSON\n\n";
+    
+    // Step 2: Deserialize with ONE LINE
+    std::cout << "📥 DESERIALIZATION (JSON → Struct)\n";
+    std::cout << "Code: GitHubUser user = simdjson::from(simdjson::padded_string(response.text));\n\n";
+    
+    GitHubUser user = simdjson::from(simdjson::padded_string(response.text));
+    
+    // Show the data we parsed
+    std::cout << "Parsed data:\n";
+    std::cout << "  • Login: " << user.login << "\n";
+    std::cout << "  • Name: " << (user.name.has_value() ? *user.name : "<not set>") << "\n";
+    std::cout << "  • Company: " << (user.company.has_value() ? *user.company : "<not set>") << "\n";
+    std::cout << "  • Location: " << (user.location.has_value() ? *user.location : "<not set>") << "\n";
+    std::cout << "  • Bio: " << (user.bio.has_value() ? *user.bio : "<not set>") << "\n";
+    std::cout << "  • Repos: " << user.public_repos << "\n";
+    std::cout << "  • Followers: " << user.followers << "\n\n";
+    
+    // Step 3: Modify the data
+    std::cout << "✏️  Modifying data...\n";
+    user.followers += 1000;  // Wishful thinking!
+    user.name = "simdjson - JSON at the speed of light";  // Set a name
+    user.bio = user.bio.value_or("") + " (Now with C++26 reflection!)";
+    std::cout << "  • Added 1000 followers (we can dream!)\n";
+    std::cout << "  • Set organization name\n";
+    std::cout << "  • Updated bio\n\n";
+    
+    // Step 4: Serialize back to JSON with ONE LINE
+    std::cout << "📤 SERIALIZATION (Struct → JSON)\n";
+    std::cout << "Code: std::string json = simdjson::builder::to_json_string(user);\n\n";
+    
+    auto json_result = simdjson::builder::to_json_string(user);
+    if (json_result.error()) {
+        std::cerr << "Serialization error!\n";
+        return 1;
+    }
+    std::string json = json_result.value();
+    
+    std::cout << "Generated JSON (" << json.length() << " bytes):\n";
+    // Pretty print first 200 chars
+    if (json.length() > 200) {
+        std::cout << json.substr(0, 200) << "...\n\n";
+    } else {
+        std::cout << json << "\n\n";
+    }
+    
+    // Step 5: Verify round-trip
+    std::cout << "🔄 ROUND-TRIP VERIFICATION\n";
+    std::cout << "Parsing our generated JSON back...\n";
+    
+    GitHubUser user2 = simdjson::from(simdjson::padded_string(json));
+    
+    std::cout << "✅ Round-trip successful!\n";
+    std::cout << "  • Original followers: " << user.followers << "\n";
+    std::cout << "  • Parsed followers: " << user2.followers << "\n";
+    std::cout << "  • Name set correctly: " << (user2.name.has_value() && *user2.name == *user.name ? "YES" : "NO") << "\n";
+    std::cout << "  • Bio preserved: " << (user2.bio.has_value() ? "YES" : "NO") << "\n\n";
+    
+    std::cout << "🎉 That's it! Two lines of code for complete JSON handling:\n";
+    std::cout << "   • Deserialization: simdjson::from(...)\n";
+    std::cout << "   • Serialization: simdjson::builder::to_json_string(...)\n";
+    
+    return 0;
+}

examples/quickstart/CMakeLists.txt

@@ -20,12 +20,16 @@ IF(${CMAKE_SYSTEM_NAME} MATCHES "Linux")
   endif()
 
   add_quickstart_test(quickstart_noexceptions   quickstart_noexceptions.cpp NO_EXCEPTIONS LABELS acceptance)
-  add_quickstart_test(quickstart_noexceptions11 quickstart_noexceptions.cpp NO_EXCEPTIONS CXX_STANDARD c++11)
+  if(NOT SIMDJSON_STATIC_REFLECTION)
+    add_quickstart_test(quickstart_noexceptions11 quickstart_noexceptions.cpp NO_EXCEPTIONS CXX_STANDARD c++11)
+  endif(NOT SIMDJSON_STATIC_REFLECTION)
 
   add_quickstart_test(quickstart2_noexceptions   quickstart2_noexceptions.cpp NO_EXCEPTIONS LABELS acceptance)
-  add_quickstart_test(quickstart2_noexceptions11 quickstart2_noexceptions.cpp NO_EXCEPTIONS CXX_STANDARD c++11)
+  if(NOT SIMDJSON_STATIC_REFLECTION)
+    add_quickstart_test(quickstart2_noexceptions11 quickstart2_noexceptions.cpp NO_EXCEPTIONS CXX_STANDARD c++11)
+  endif(NOT SIMDJSON_STATIC_REFLECTION)
 
-  # On Demand Quick Start
+  # On-Demand Quick Start
   if (SIMDJSON_EXCEPTIONS)
     add_quickstart_test(quickstart_ondemand   quickstart_ondemand.cpp LABELS quickstart_ondemand acceptance)
     add_quickstart_test(quickstart_ondemand11 quickstart_ondemand.cpp CXX_STANDARD c++11 LABELS quickstart_ondemand acceptance)
@@ -33,6 +37,8 @@ IF(${CMAKE_SYSTEM_NAME} MATCHES "Linux")
   endif()
 
   add_quickstart_test(quickstart_ondemand_noexceptions   quickstart_ondemand_noexceptions.cpp NO_EXCEPTIONS LABELS quickstart_ondemand acceptance)
-  add_quickstart_test(quickstart_ondemand_noexceptions11 quickstart_ondemand_noexceptions.cpp NO_EXCEPTIONS CXX_STANDARD c++11 LABELS quickstart_ondemand)
+  if(NOT SIMDJSON_STATIC_REFLECTION)
+    add_quickstart_test(quickstart_ondemand_noexceptions11 quickstart_ondemand_noexceptions.cpp NO_EXCEPTIONS CXX_STANDARD c++11 LABELS quickstart_ondemand)
+  endif(NOT SIMDJSON_STATIC_REFLECTION)
 
 endif()

examples/reflection_roundtrip_demo.cpp

@@ -0,0 +1,86 @@
+// Complete JSON Round-Trip Demo with C++26 Reflection
+// Compile with: clang++ -std=c++26 -freflection -DSIMDJSON_STATIC_REFLECTION=1 reflection_roundtrip_demo.cpp ../singleheader/simdjson.cpp -o reflection_roundtrip_demo
+#include <iostream>
+#include <vector>
+#include <optional>
+#include "simdjson.h"
+
+// Define our data structure - just a plain struct!
+struct Product {
+    std::string name;
+    double price;
+    std::vector<std::string> tags;
+    std::optional<std::string> description;
+    bool in_stock;
+};
+
+int main() {
+    std::cout << "🔄 simdjson C++26 Reflection Round-Trip Demo\n";
+    std::cout << "============================================\n\n";
+    
+    // Original JSON data
+    const char* json_data = R"({
+        "name": "High-Performance JSON Parser",
+        "price": 0.0,
+        "tags": ["C++", "performance", "json", "reflection"],
+        "description": "The fastest JSON parser with C++26 reflection support",
+        "in_stock": true
+    })";
+    
+    std::cout << "📄 Original JSON:\n" << json_data << "\n\n";
+    
+    // Step 1: Deserialize JSON to struct with ONE line
+    std::cout << "📥 Deserializing JSON → Struct...\n";
+    Product product = simdjson::from(simdjson::padded_string(json_data));
+    
+    std::cout << "✅ Deserialized successfully!\n";
+    std::cout << "   • Name: " << product.name << "\n";
+    std::cout << "   • Price: $" << product.price << "\n";
+    std::cout << "   • Tags: ";
+    for (const auto& tag : product.tags) {
+        std::cout << tag << " ";
+    }
+    std::cout << "\n   • In stock: " << (product.in_stock ? "Yes" : "No") << "\n\n";
+    
+    // Step 2: Modify the data
+    std::cout << "✏️  Modifying data...\n";
+    product.price = 99.99;  // It's worth something now!
+    product.tags.push_back("C++26");
+    product.description = "Now with serialization support!";
+    std::cout << "   • Changed price to $99.99\n";
+    std::cout << "   • Added 'C++26' tag\n";
+    std::cout << "   • Updated description\n\n";
+    
+    // Step 3: Serialize struct back to JSON with ONE line
+    std::cout << "📤 Serializing Struct → JSON...\n";
+    auto json_result = simdjson::builder::to_json_string(product);
+    
+    if (json_result.error()) {
+        std::cerr << "❌ Serialization failed!\n";
+        return 1;
+    }
+    
+    std::string new_json = json_result.value();
+    std::cout << "✅ Serialized successfully!\n\n";
+    
+    std::cout << "📄 Generated JSON:\n" << new_json << "\n\n";
+    
+    // Step 4: Verify round-trip by parsing again
+    std::cout << "🔍 Verifying round-trip...\n";
+    Product product2 = simdjson::from(simdjson::padded_string(new_json));
+    
+    std::cout << "✅ Round-trip successful!\n";
+    std::cout << "   • Price preserved: $" << product2.price << "\n";
+    std::cout << "   • New tag present: " 
+              << (std::find(product2.tags.begin(), product2.tags.end(), "C++26") != product2.tags.end() ? "Yes" : "No") 
+              << "\n";
+    std::cout << "   • Description updated: " << (product2.description.has_value() ? "Yes" : "No") << "\n\n";
+    
+    std::cout << "🎉 That's it! Complete JSON handling in just 2 lines:\n";
+    std::cout << "   • Deserialize: auto obj = simdjson::from(json);\n";
+    std::cout << "   • Serialize: auto json = simdjson::builder::to_json_string(obj);\n\n";
+    
+    std::cout << "⚡ No manual parsing, no boilerplate, just pure C++26 magic!\n";
+    
+    return 0;
+}

examples/serialization_benchmark.cpp

@@ -0,0 +1,85 @@
+#include <iostream>
+#include <iomanip>
+#include <chrono>
+#include "simdjson.h"
+#include <map>
+
+struct TestData {
+    std::string name;
+    std::vector<int> numbers;
+    std::map<std::string, double> metrics;
+    bool active;
+    std::optional<std::string> description;
+};
+
+int main() {
+    std::cout << "⚡ Serialization Performance Benchmark\n";
+    std::cout << "=====================================\n\n";
+    
+    // Create test data
+    TestData data{
+        .name = "Performance Test",
+        .numbers = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10},
+        .metrics = {{"latency", 1.23}, {"throughput", 456.78}, {"cpu", 89.01}},
+        .active = true,
+        .description = "Testing reflection-based serialization performance"
+    };
+    
+    const int iterations = 100000;
+    
+    // Benchmark serialization
+    std::cout << "📤 Benchmarking serialization (" << iterations << " iterations)...\n";
+    
+    auto start = std::chrono::high_resolution_clock::now();
+    
+    std::string json;
+    for (int i = 0; i < iterations; i++) {
+        auto result = simdjson::builder::to_json_string(data);
+        if (i == 0 && !result.error()) {
+            json = result.value();
+        }
+    }
+    
+    auto end = std::chrono::high_resolution_clock::now();
+    auto duration = std::chrono::duration_cast<std::chrono::microseconds>(end - start);
+    
+    std::cout << "\nResults:\n";
+    std::cout << "  • Generated JSON size: " << json.length() << " bytes\n";
+    std::cout << "  • Total time: " << duration.count() / 1000.0 << " ms\n";
+    
+    double time_per_iteration_us = duration.count() / double(iterations);
+    double time_per_iteration_s = time_per_iteration_us / 1000000.0;
+    double bytes_per_second = json.length() / time_per_iteration_s;
+    double mb_per_second = bytes_per_second / (1024.0 * 1024.0);
+    
+    std::cout << "  • Time per serialization: " << std::fixed << std::setprecision(2) << time_per_iteration_us << " μs\n";
+    std::cout << "  • Throughput: " << std::fixed << std::setprecision(2) << mb_per_second << " MB/s\n";
+    
+    std::cout << "\nGenerated JSON:\n" << json << "\n\n";
+    
+    // Benchmark deserialization for comparison
+    std::cout << "📥 Benchmarking deserialization (for comparison)...\n";
+    
+    simdjson::padded_string padded_json(json);
+    start = std::chrono::high_resolution_clock::now();
+    
+    for (int i = 0; i < iterations; i++) {
+        TestData parsed = simdjson::from(padded_json);
+    }
+    
+    end = std::chrono::high_resolution_clock::now();
+    duration = std::chrono::duration_cast<std::chrono::microseconds>(end - start);
+    
+    std::cout << "\nResults:\n";
+    time_per_iteration_us = duration.count() / double(iterations);
+    time_per_iteration_s = time_per_iteration_us / 1000000.0;
+    bytes_per_second = json.length() / time_per_iteration_s;
+    mb_per_second = bytes_per_second / (1024.0 * 1024.0);
+    
+    std::cout << "  • Time per deserialization: " << std::fixed << std::setprecision(2) << time_per_iteration_us << " μs\n";
+    std::cout << "  • Throughput: " << std::fixed << std::setprecision(2) << mb_per_second << " MB/s\n";
+    
+    std::cout << "\n✅ Both serialization and deserialization work with reflection!\n";
+    
+    return 0;
+}

fuzz/fuzz_implementations.cpp

@@ -72,7 +72,7 @@ extern "C" int LLVMFuzzerTestOneInput(const uint8_t *Data, size_t Size) {
 
     // make this dynamic, so it works regardless of how it was compiled
     // or what hardware it runs on
-    constexpr std::size_t Nimplementations_max=3;
+    constexpr std::size_t Nimplementations_max=4;
     const std::size_t Nimplementations = supported_implementations.size();
 
     if(Nimplementations>Nimplementations_max) {

include/simdjson.h

@@ -53,5 +53,5 @@
 
 #include "simdjson/dom.h"
 #include "simdjson/ondemand.h"
-
+#include "simdjson/convert.h"
 #endif // SIMDJSON_H

include/simdjson/arm64/bitmanipulation.h

@@ -19,7 +19,7 @@ SIMDJSON_NO_SANITIZE_UNDEFINED
 // See issue https://github.com/simdjson/simdjson/issues/1965
 SIMDJSON_NO_SANITIZE_MEMORY
 simdjson_inline int trailing_zeroes(uint64_t input_num) {
-#ifdef SIMDJSON_REGULAR_VISUAL_STUDIO
+#if SIMDJSON_REGULAR_VISUAL_STUDIO
   unsigned long ret;
   // Search the mask data from least significant bit (LSB)
   // to the most significant bit (MSB) for a set bit (1).
@@ -35,9 +35,15 @@ simdjson_inline uint64_t clear_lowest_bit(uint64_t input_num) {
   return input_num & (input_num-1);
 }
 
+// We sometimes call leading_zeroes on inputs that are zero,
+// but the algorithms do not end up using the returned value.
+// Sadly, sanitizers are not smart enough to figure it out.
+// Applies only when SIMDJSON_PREFER_REVERSE_BITS is defined and true.
+// (See below.)
+SIMDJSON_NO_SANITIZE_UNDEFINED
 /* result might be undefined when input_num is zero */
 simdjson_inline int leading_zeroes(uint64_t input_num) {
-#ifdef SIMDJSON_REGULAR_VISUAL_STUDIO
+#if SIMDJSON_REGULAR_VISUAL_STUDIO
   unsigned long leading_zero = 0;
   // Search the mask data from most significant bit (MSB)
   // to least significant bit (LSB) for a set bit (1).
@@ -90,7 +96,7 @@ simdjson_inline uint64_t zero_leading_bit(uint64_t rev_bits, int leading_zeroes)
 #endif
 
 simdjson_inline bool add_overflow(uint64_t value1, uint64_t value2, uint64_t *result) {
-#ifdef SIMDJSON_REGULAR_VISUAL_STUDIO
+#if SIMDJSON_REGULAR_VISUAL_STUDIO
   *result = value1 + value2;
   return *result < value1;
 #else

include/simdjson/arm64/numberparsing_defs.h

@@ -51,6 +51,12 @@ simdjson_inline internal::value128 full_multiplication(uint64_t value1, uint64_t
 } // namespace arm64
 } // namespace simdjson
 
+#ifndef SIMDJSON_SWAR_NUMBER_PARSING
+#if SIMDJSON_IS_BIG_ENDIAN
+#define SIMDJSON_SWAR_NUMBER_PARSING 0
+#else
 #define SIMDJSON_SWAR_NUMBER_PARSING 1
+#endif
+#endif
 
 #endif // SIMDJSON_ARM64_NUMBERPARSING_DEFS_H

include/simdjson/arm64/simd.h

@@ -12,7 +12,7 @@ namespace arm64 {
 namespace {
 namespace simd {
 
-#ifdef SIMDJSON_REGULAR_VISUAL_STUDIO
+#if SIMDJSON_REGULAR_VISUAL_STUDIO
 namespace {
 // Start of private section with Visual Studio workaround
 
@@ -121,7 +121,7 @@ namespace {
     // We return uint32_t instead of uint16_t because that seems to be more efficient for most
     // purposes (cutting it down to uint16_t costs performance in some compilers).
     simdjson_inline uint32_t to_bitmask() const {
-#ifdef SIMDJSON_REGULAR_VISUAL_STUDIO
+#if SIMDJSON_REGULAR_VISUAL_STUDIO
       const uint8x16_t bit_mask =  simdjson_make_uint8x16_t(0x01, 0x02, 0x4, 0x8, 0x10, 0x20, 0x40, 0x80,
                                                    0x01, 0x02, 0x4, 0x8, 0x10, 0x20, 0x40, 0x80);
 #else
@@ -134,6 +134,12 @@ namespace {
       tmp = vpaddq_u8(tmp, tmp);
       return vgetq_lane_u16(vreinterpretq_u16_u8(tmp), 0);
     }
+    // Returns 4-bit out of each byte, alternating between the high 4 bits and low
+    // bits result it is 64 bit.
+    simdjson_inline uint64_t to_bitmask64() const {
+      return vget_lane_u64(
+          vreinterpret_u64_u8(vshrn_n_u16(vreinterpretq_u16_u8(*this), 4)), 0);
+    }
     simdjson_inline bool any() const { return vmaxvq_u32(vreinterpretq_u32_u8(*this)) != 0; }
   };
 
@@ -152,7 +158,7 @@ namespace {
     // Splat constructor
     simdjson_inline simd8(uint8_t _value) : simd8(splat(_value)) {}
     // Member-by-member initialization
-#ifdef SIMDJSON_REGULAR_VISUAL_STUDIO
+#if SIMDJSON_REGULAR_VISUAL_STUDIO
     simdjson_inline simd8(
       uint8_t v0,  uint8_t v1,  uint8_t v2,  uint8_t v3,  uint8_t v4,  uint8_t v5,  uint8_t v6,  uint8_t v7,
       uint8_t v8,  uint8_t v9,  uint8_t v10, uint8_t v11, uint8_t v12, uint8_t v13, uint8_t v14, uint8_t v15
@@ -210,7 +216,7 @@ namespace {
 
     // Bit-specific operations
     simdjson_inline simd8<bool> any_bits_set(simd8<uint8_t> bits) const { return vtstq_u8(*this, bits); }
-    simdjson_inline bool any_bits_set_anywhere() const { return this->max_val() != 0; }
+    simdjson_inline bool any_bits_set_anywhere() const { return vmaxvq_u32(vreinterpretq_u32_u8(*this)) != 0; }
     simdjson_inline bool any_bits_set_anywhere(simd8<uint8_t> bits) const { return (*this & bits).any_bits_set_anywhere(); }
     template<int N>
     simdjson_inline simd8<uint8_t> shr() const { return vshrq_n_u8(*this, N); }
@@ -223,7 +229,12 @@ namespace {
       return lookup_table.apply_lookup_16_to(*this);
     }
 
-
+    // Returns 4-bit out of each byte, alternating between the high 4 bits and low
+    // bits result it is 64 bit.
+    simdjson_inline uint64_t to_bitmask64() const {
+      return vget_lane_u64(
+          vreinterpret_u64_u8(vshrn_n_u16(vreinterpretq_u16_u8(*this), 4)), 0);
+    }
     // Copies to 'output" all bytes corresponding to a 0 in the mask (interpreted as a bitset).
     // Passing a 0 value for mask would be equivalent to writing out every byte to output.
     // Only the first 16 - count_ones(mask) bytes of the result are significant but 16 bytes
@@ -246,7 +257,7 @@ namespace {
       uint64x2_t shufmask64 = {thintable_epi8[mask1], thintable_epi8[mask2]};
       uint8x16_t shufmask = vreinterpretq_u8_u64(shufmask64);
       // we increment by 0x08 the second half of the mask
-#ifdef SIMDJSON_REGULAR_VISUAL_STUDIO
+#if SIMDJSON_REGULAR_VISUAL_STUDIO
       uint8x16_t inc = simdjson_make_uint8x16_t(0, 0, 0, 0, 0, 0, 0, 0, 0x08, 0x08, 0x08, 0x08, 0x08, 0x08, 0x08, 0x08);
 #else
       uint8x16_t inc = {0, 0, 0, 0, 0, 0, 0, 0, 0x08, 0x08, 0x08, 0x08, 0x08, 0x08, 0x08, 0x08};
@@ -276,7 +287,7 @@ namespace {
       uint8x8_t compactmask1 = vcreate_u8(thintable_epi8[mask1]);
       uint8x8_t compactmask2 = vcreate_u8(thintable_epi8[mask2]);
       // we increment by 0x08 the second half of the mask
-#ifdef SIMDJSON_REGULAR_VISUAL_STUDIO
+#if SIMDJSON_REGULAR_VISUAL_STUDIO
       uint8x8_t inc = simdjson_make_uint8x8_t(0x08, 0x08, 0x08, 0x08, 0x08, 0x08, 0x08, 0x08);
 #else
       uint8x8_t inc = {0x08, 0x08, 0x08, 0x08, 0x08, 0x08, 0x08, 0x08};
@@ -328,7 +339,7 @@ namespace {
     // Array constructor
     simdjson_inline simd8(const int8_t* values) : simd8(load(values)) {}
     // Member-by-member initialization
-#ifdef SIMDJSON_REGULAR_VISUAL_STUDIO
+#if SIMDJSON_REGULAR_VISUAL_STUDIO
     simdjson_inline simd8(
       int8_t v0,  int8_t v1,  int8_t v2,  int8_t v3, int8_t v4,  int8_t v5,  int8_t v6,  int8_t v7,
       int8_t v8,  int8_t v9,  int8_t v10, int8_t v11, int8_t v12, int8_t v13, int8_t v14, int8_t v15
@@ -449,7 +460,7 @@ namespace {
     }
 
     simdjson_inline uint64_t to_bitmask() const {
-#ifdef SIMDJSON_REGULAR_VISUAL_STUDIO
+#if SIMDJSON_REGULAR_VISUAL_STUDIO
       const uint8x16_t bit_mask = simdjson_make_uint8x16_t(
         0x01, 0x02, 0x4, 0x8, 0x10, 0x20, 0x40, 0x80,
         0x01, 0x02, 0x4, 0x8, 0x10, 0x20, 0x40, 0x80

include/simdjson/arm64/stringparsing_defs.h

@@ -46,6 +46,32 @@ simdjson_inline backslash_and_quote backslash_and_quote::copy_and_find(const uin
   };
 }
 
+struct escaping {
+  static constexpr uint32_t BYTES_PROCESSED = 16;
+  simdjson_inline static escaping copy_and_find(const uint8_t *src, uint8_t *dst);
+
+  simdjson_inline bool has_escape() { return escape_bits != 0; }
+  simdjson_inline int escape_index() { return trailing_zeroes(escape_bits) / 4; }
+
+  uint64_t escape_bits;
+}; // struct escaping
+
+
+
+simdjson_inline escaping escaping::copy_and_find(const uint8_t *src, uint8_t *dst) {
+  static_assert(SIMDJSON_PADDING >= (BYTES_PROCESSED - 1), "escaping finder must process fewer than SIMDJSON_PADDING bytes");
+  simd8<uint8_t> v(src);
+  v.store(dst);
+  simd8<bool> is_quote = (v == '"');
+  simd8<bool> is_backslash = (v == '\\');
+  simd8<bool> is_control = (v < 32);
+  return {
+    (is_backslash | is_quote | is_control).to_bitmask64()
+  };
+}
+
+
+
 } // unnamed namespace
 } // namespace arm64
 } // namespace simdjson

include/simdjson/base.h

@@ -9,6 +9,7 @@
 #include "simdjson/compiler_check.h"
 #include "simdjson/error.h"
 #include "simdjson/portability.h"
+#include "simdjson/concepts.h"
 
 /**
  * @brief The top level simdjson namespace, containing everything the library provides.

include/simdjson/common_defs.h

@@ -23,7 +23,7 @@ double from_chars(const char *first, const char* end) noexcept;
 }
 
 #ifndef SIMDJSON_EXCEPTIONS
-#if __cpp_exceptions
+#if defined(__cpp_exceptions) || defined(_CPPUNWIND)
 #define SIMDJSON_EXCEPTIONS 1
 #else
 #define SIMDJSON_EXCEPTIONS 0
@@ -50,6 +50,8 @@ double from_chars(const char *first, const char* end) noexcept;
 #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
+  #define simdjson_deprecated __declspec(deprecated)
 
   #define simdjson_really_inline __forceinline
   #define simdjson_never_inline __declspec(noinline)
@@ -88,6 +90,8 @@ double from_chars(const char *first, const char* end) noexcept;
   #define SIMDJSON_POP_DISABLE_UNUSED_WARNINGS
 
 #else // SIMDJSON_REGULAR_VISUAL_STUDIO
+  // We could use [[deprecated]] but it requires C++14
+  #define simdjson_deprecated __attribute__((deprecated))
 
   #define simdjson_really_inline inline __attribute__((always_inline))
   #define simdjson_never_inline inline __attribute__((noinline))
@@ -195,17 +199,6 @@ double from_chars(const char *first, const char* end) noexcept;
     // We assume by default static linkage
     #define SIMDJSON_DLLIMPORTEXPORT
     #endif
-
-/**
- * Workaround for the vcpkg package manager. Only vcpkg should
- * ever touch the next line. The SIMDJSON_USING_LIBRARY macro is otherwise unused.
- */
-#if SIMDJSON_USING_LIBRARY
-#define SIMDJSON_DLLIMPORTEXPORT __declspec(dllimport)
-#endif
-/**
- * End of workaround for the vcpkg package manager.
- */
 #else
     #define SIMDJSON_DLLIMPORTEXPORT
 #endif
@@ -222,12 +215,14 @@ double from_chars(const char *first, const char* end) noexcept;
 // even if we do not have C++17 support.
 #ifdef __cpp_lib_string_view
 #define SIMDJSON_HAS_STRING_VIEW
+#include <string_view>
 #endif
 
 // Some systems have string_view even if we do not have C++17 support,
 // and even if __cpp_lib_string_view is undefined, it is the case
 // with Apple clang version 11.
 // We must handle it. *This is important.*
+#ifndef _MSC_VER
 #ifndef SIMDJSON_HAS_STRING_VIEW
 #if defined __has_include
 // do not combine the next #if with the previous one (unsafe)
@@ -243,6 +238,7 @@ double from_chars(const char *first, const char* end) noexcept;
 #endif // __has_include (<string_view>)
 #endif // defined __has_include
 #endif // def SIMDJSON_HAS_STRING_VIEW
+#endif // def _MSC_VER
 // end of complicated but important routine to try to detect string_view.
 
 //
@@ -275,16 +271,25 @@ namespace std {
 // It could also wrongly set SIMDJSON_DEVELOPMENT_CHECKS (e.g., if the programmer
 // sets _DEBUG in a release build under Visual Studio, or if some compiler fails to
 // set the __OPTIMIZE__ macro).
+// We make it so that if NDEBUG is defined, then SIMDJSON_DEVELOPMENT_CHECKS
+// is not defined, irrespective of the compiler.
+// We recommend that users set NDEBUG in release builds, so that
+// SIMDJSON_DEVELOPMENT_CHECKS is not defined in release builds by default,
+// irrespective of the compiler.
 #ifndef SIMDJSON_DEVELOPMENT_CHECKS
 #ifdef _MSC_VER
 // Visual Studio seems to set _DEBUG for debug builds.
-#ifdef _DEBUG
+// We set SIMDJSON_DEVELOPMENT_CHECKS to 1 if _DEBUG is defined
+// and NDEBUG is not defined.
+#if defined(_DEBUG) && !defined(NDEBUG)
 #define SIMDJSON_DEVELOPMENT_CHECKS 1
 #endif // _DEBUG
 #else // _MSC_VER
 // All other compilers appear to set __OPTIMIZE__ to a positive integer
 // when the compiler is optimizing.
-#ifndef __OPTIMIZE__
+// We only set SIMDJSON_DEVELOPMENT_CHECKS if both __OPTIMIZE__
+// and NDEBUG are not defined.
+#if !defined(__OPTIMIZE__) && !defined(NDEBUG)
 #define SIMDJSON_DEVELOPMENT_CHECKS 1
 #endif // __OPTIMIZE__
 #endif // _MSC_VER
@@ -340,4 +345,16 @@ namespace std {
 #define SIMDJSON_AVX512_ALLOWED 1
 #endif
 
+
+#ifndef __has_cpp_attribute
+#define simdjson_lifetime_bound
+#elif __has_cpp_attribute(msvc::lifetimebound)
+#define simdjson_lifetime_bound [[msvc::lifetimebound]]
+#elif __has_cpp_attribute(clang::lifetimebound)
+#define simdjson_lifetime_bound [[clang::lifetimebound]]
+#elif __has_cpp_attribute(lifetimebound)
+#define simdjson_lifetime_bound [[lifetimebound]]
+#else
+#define simdjson_lifetime_bound
+#endif
 #endif // SIMDJSON_COMMON_DEFS_H

include/simdjson/compiler_check.h

@@ -13,6 +13,16 @@
 #endif
 #endif
 
+// C++ 23
+#if !defined(SIMDJSON_CPLUSPLUS23) && (SIMDJSON_CPLUSPLUS >= 202302L)
+#define SIMDJSON_CPLUSPLUS23 1
+#endif
+
+// C++ 20
+#if !defined(SIMDJSON_CPLUSPLUS20) && (SIMDJSON_CPLUSPLUS >= 202002L)
+#define SIMDJSON_CPLUSPLUS20 1
+#endif
+
 // C++ 17
 #if !defined(SIMDJSON_CPLUSPLUS17) && (SIMDJSON_CPLUSPLUS >= 201703L)
 #define SIMDJSON_CPLUSPLUS17 1
@@ -40,4 +50,55 @@
 #endif
 #endif
 
+#ifndef SIMDJSON_CONSTEXPR_LAMBDA
+#if SIMDJSON_CPLUSPLUS17
+#define SIMDJSON_CONSTEXPR_LAMBDA constexpr
+#else
+#define SIMDJSON_CONSTEXPR_LAMBDA
+#endif
+#endif
+
+
+
+#ifdef __has_include
+#if __has_include(<version>)
+#include <version>
+#endif
+#endif
+
+// The current specification is unclear on how we detect
+// static reflection, both __cpp_lib_reflection and
+// __cpp_impl_reflection are proposed in the draft specification.
+// For now, we disable static reflect by default. It must be
+// specified at compiler time.
+#ifndef SIMDJSON_STATIC_REFLECTION
+#define SIMDJSON_STATIC_REFLECTION 0 // disabled by default.
+#endif
+
+#if defined(__apple_build_version__)
+#if __apple_build_version__ < 14000000
+#define SIMDJSON_CONCEPT_DISABLED 1 // apple-clang/13 doesn't support std::convertible_to
+#endif
+#endif
+
+
+#if defined(__cpp_concepts) && !defined(SIMDJSON_CONCEPT_DISABLED)
+#if __cpp_concepts >= 201907L
+#include <utility>
+#define SIMDJSON_SUPPORTS_DESERIALIZATION 1
+#else
+#define SIMDJSON_SUPPORTS_DESERIALIZATION 0
+#endif
+#else // defined(__cpp_concepts) && !defined(SIMDJSON_CONCEPT_DISABLED)
+#define SIMDJSON_SUPPORTS_DESERIALIZATION 0
+#endif // defined(__cpp_concepts) && !defined(SIMDJSON_CONCEPT_DISABLED)
+
+#if !defined(SIMDJSON_CONSTEVAL)
+#if defined(__cpp_consteval) && __cpp_consteval >= 201811L
+#define SIMDJSON_CONSTEVAL 1
+#else
+#define SIMDJSON_CONSTEVAL 0
+#endif // defined(__cpp_consteval) && __cpp_consteval >= 201811L
+#endif // !defined(SIMDJSON_CONSTEVAL)
+
 #endif // SIMDJSON_COMPILER_CHECK_H

include/simdjson/concepts.h

@@ -0,0 +1,130 @@
+#ifndef SIMDJSON_CONCEPTS_H
+#define SIMDJSON_CONCEPTS_H
+#if SIMDJSON_SUPPORTS_DESERIALIZATION
+
+#include <concepts>
+#include <type_traits>
+
+namespace simdjson {
+namespace concepts {
+
+namespace details {
+#define SIMDJSON_IMPL_CONCEPT(name, method)                                    \
+  template <typename T>                                                        \
+  concept supports_##name = !std::is_const_v<T> && requires {                  \
+    typename std::remove_cvref_t<T>::value_type;                               \
+    requires requires(typename std::remove_cvref_t<T>::value_type &&val,       \
+                      T obj) {                                                 \
+      obj.method(std::move(val));                                              \
+      requires !requires { obj = std::move(val); };                            \
+    };                                                                         \
+  };
+
+SIMDJSON_IMPL_CONCEPT(emplace_back, emplace_back)
+SIMDJSON_IMPL_CONCEPT(emplace, emplace)
+SIMDJSON_IMPL_CONCEPT(push_back, push_back)
+SIMDJSON_IMPL_CONCEPT(add, add)
+SIMDJSON_IMPL_CONCEPT(push, push)
+SIMDJSON_IMPL_CONCEPT(append, append)
+SIMDJSON_IMPL_CONCEPT(insert, insert)
+SIMDJSON_IMPL_CONCEPT(op_append, operator+=)
+
+#undef SIMDJSON_IMPL_CONCEPT
+} // namespace details
+
+
+template <typename T>
+concept string_view_like = std::is_convertible_v<T, std::string_view> &&
+                           !std::is_convertible_v<T, const char*>;
+
+template<typename T>
+concept constructible_from_string_view = std::is_constructible_v<T, std::string_view>
+                                        && !std::is_same_v<T, std::string_view>
+                                        && std::is_default_constructible_v<T>;
+
+template<typename M>
+concept string_view_keyed_map = string_view_like<typename M::key_type>
+              && requires(std::remove_cvref_t<M>& m, typename M::key_type sv, typename M::mapped_type v) {
+    { m.emplace(sv, v) } -> std::same_as<std::pair<typename M::iterator, bool>>;
+};
+
+/// Check if T is a container that we can append to, including:
+///   std::vector, std::deque, std::list, std::string, ...
+template <typename T>
+concept appendable_containers =
+    (details::supports_emplace_back<T> || details::supports_emplace<T> ||
+    details::supports_push_back<T> || details::supports_push<T> ||
+    details::supports_add<T> || details::supports_append<T> ||
+    details::supports_insert<T>) && !string_view_keyed_map<T>;
+
+/// Insert into the container however possible
+template <appendable_containers T, typename... Args>
+constexpr decltype(auto) emplace_one(T &vec, Args &&...args) {
+  if constexpr (details::supports_emplace_back<T>) {
+    return vec.emplace_back(std::forward<Args>(args)...);
+  } else if constexpr (details::supports_emplace<T>) {
+    return vec.emplace(std::forward<Args>(args)...);
+  } else if constexpr (details::supports_push_back<T>) {
+    return vec.push_back(std::forward<Args>(args)...);
+  } else if constexpr (details::supports_push<T>) {
+    return vec.push(std::forward<Args>(args)...);
+  } else if constexpr (details::supports_add<T>) {
+    return vec.add(std::forward<Args>(args)...);
+  } else if constexpr (details::supports_append<T>) {
+    return vec.append(std::forward<Args>(args)...);
+  } else if constexpr (details::supports_insert<T>) {
+    return vec.insert(std::forward<Args>(args)...);
+  } else if constexpr (details::supports_op_append<T> && sizeof...(Args) == 1) {
+    return vec.operator+=(std::forward<Args>(args)...);
+  } else {
+    static_assert(!sizeof(T *),
+                  "We don't know how to add things to this container");
+  }
+}
+
+/// This checks if the container will return a reference to the newly added
+/// element after an insert which for example `std::vector::emplace_back` does
+/// since C++17; this will allow some optimizations.
+template <typename T>
+concept returns_reference = appendable_containers<T> && requires {
+  typename std::remove_cvref_t<T>::reference;
+  requires requires(typename std::remove_cvref_t<T>::value_type &&val, T obj) {
+    {
+      emplace_one(obj, std::move(val))
+    } -> std::same_as<typename std::remove_cvref_t<T>::reference>;
+  };
+};
+
+template <typename T>
+concept smart_pointer = requires(std::remove_cvref_t<T> ptr) {
+  // Check if T has a member type named element_type
+  typename std::remove_cvref_t<T>::element_type;
+
+  // Check if T has a get() member function
+  {
+    ptr.get()
+  } -> std::same_as<typename std::remove_cvref_t<T>::element_type *>;
+
+  // Check if T can be dereferenced
+  { *ptr } -> std::same_as<typename std::remove_cvref_t<T>::element_type &>;
+};
+
+template <typename T>
+concept optional_type = requires(std::remove_cvref_t<T> obj) {
+  typename std::remove_cvref_t<T>::value_type;
+  { obj.value() } -> std::same_as<typename std::remove_cvref_t<T>::value_type&>;
+  requires requires(typename std::remove_cvref_t<T>::value_type &&val) {
+    obj.emplace(std::move(val));
+    {
+      obj.value_or(val)
+    } -> std::convertible_to<typename std::remove_cvref_t<T>::value_type>;
+  };
+  { static_cast<bool>(obj) } -> std::same_as<bool>; // convertible to bool
+};
+
+
+
+} // namespace concepts
+} // namespace simdjson
+#endif // SIMDJSON_SUPPORTS_DESERIALIZATION
+#endif // SIMDJSON_CONCEPTS_H

include/simdjson/convert.h

@@ -0,0 +1,307 @@
+#ifndef SIMDJSON_CONVERT_H
+#define SIMDJSON_CONVERT_H
+#if __cpp_concepts
+
+#include "simdjson/ondemand.h"
+#include <optional>
+#ifdef __cpp_lib_ranges
+#include <ranges>
+#endif
+
+namespace simdjson {
+
+struct [[nodiscard]] auto_iterator_end {};
+
+/**
+ * A Wrapper for simdjson_result<ondemand::array_iterator> in order to make it
+ * compatible with ranges (to satisfy std::ranges::input_range).
+ */
+struct [[nodiscard]] auto_iterator {
+  using iterator_category = std::forward_iterator_tag;
+  using type = simdjson_result<ondemand::array_iterator>;
+  using value_type = simdjson_result<ondemand::value>; // type::value_type
+  using reference = value_type &;
+  using const_reference = const value_type &;
+  using difference_type = std::ptrdiff_t;
+
+  struct auto_iterator_storage {
+    type m_iter{};
+    mutable value_type m_value{};
+  };
+
+private:
+  auto_iterator_storage *m_storage = nullptr;
+
+public:
+  constexpr auto_iterator() noexcept = default;
+  explicit auto_iterator(auto_iterator_storage &storage) noexcept
+      : m_storage{&storage} {};
+  auto_iterator(auto_iterator const &) = default;
+  auto_iterator(auto_iterator &&) = default;
+  auto_iterator &operator=(auto_iterator const &) = default;
+  auto_iterator &operator=(auto_iterator &&) noexcept = default;
+  ~auto_iterator() = default;
+
+  reference operator*() const noexcept { return m_storage->m_value; }
+  reference operator*() noexcept { return m_storage->m_value; }
+
+  auto_iterator &operator++() noexcept {
+    ++m_storage->m_iter;
+    m_storage->m_value =
+        m_storage->m_iter.at_end() || m_storage->m_iter.error() != SUCCESS
+            ? value_type{}
+            : *m_storage->m_iter;
+    return *this;
+  }
+  auto_iterator operator++(int) noexcept {
+    auto_iterator const tmp = *this;
+    operator++();
+    return tmp;
+  }
+
+  [[nodiscard]] bool operator==(auto_iterator const &other) const noexcept {
+    return m_storage == other.m_storage &&
+           m_storage->m_iter == other.m_storage->m_iter;
+  }
+
+  [[nodiscard]] bool operator==(auto_iterator_end) const noexcept {
+    return m_storage != nullptr && m_storage->m_iter.at_end();
+  }
+};
+
+template <typename ParserType = ondemand::parser>
+struct [[nodiscard]] auto_parser
+#if __cpp_lib_ranges
+    : std::ranges::view_interface<auto_parser<ParserType>>
+#endif
+{
+  using value_type = simdjson_result<ondemand::value>;
+  using size_type = size_t;
+  using difference_type = std::ptrdiff_t;
+  using pointer = value_type *;
+  using const_pointer = const value_type *;
+  using reference = value_type &;
+  using const_reference = const value_type &;
+  using iterator = auto_iterator;
+  using const_iterator = auto_iterator; // auto_iterator is already const
+
+private:
+  ParserType m_parser;
+  ondemand::document m_doc;
+  error_code m_error{SUCCESS};
+
+  // Caching the iterator here:
+  iterator::auto_iterator_storage iter_storage{};
+
+  template <typename T>
+  static constexpr bool is_nothrow_gettable = requires(ondemand::document doc) {
+    { doc.get<T>() } noexcept;
+  };
+
+public:
+  // non-pointer constructors:
+  explicit auto_parser(ParserType &&parser, ondemand::document &&doc) noexcept
+    requires(!std::is_pointer_v<ParserType>)
+      : m_parser{std::move(parser)}, m_doc{std::move(doc)} {}
+
+  explicit auto_parser(ParserType &&parser,
+                       padded_string_view const str) noexcept
+    requires(!std::is_pointer_v<ParserType>)
+      : m_parser{std::move(parser)}, m_doc{}, m_error{SUCCESS} {
+    m_error = m_parser.iterate(str).get(m_doc);
+  }
+
+  explicit auto_parser(padded_string_view const str) noexcept
+    requires(!std::is_pointer_v<ParserType>)
+      : auto_parser{ParserType{}, str} {}
+
+  // pointer constructors:
+  explicit auto_parser(std::remove_pointer_t<ParserType> &parser,
+                       ondemand::document &&doc) noexcept
+    requires(std::is_pointer_v<ParserType>)
+      : m_parser{&parser}, m_doc{std::move(doc)} {}
+
+  explicit auto_parser(std::remove_pointer_t<ParserType> &parser,
+                       padded_string_view const str) noexcept
+    requires(std::is_pointer_v<ParserType>)
+      : m_parser{&parser}, m_doc{}, m_error{SUCCESS} {
+    m_error = m_parser->iterate(str).get(m_doc);
+  }
+
+  explicit auto_parser(ParserType parser, ondemand::document &&doc) noexcept
+    requires(std::is_pointer_v<ParserType>)
+      : auto_parser{*parser, std::move(doc)} {}
+
+  auto_parser(auto_parser const &) = delete;
+  auto_parser &operator=(auto_parser const &) = delete;
+  auto_parser(auto_parser &&) noexcept = default;
+  auto_parser &operator=(auto_parser &&) noexcept = default;
+  ~auto_parser() = default;
+
+  /// Get the parser
+  [[nodiscard]] std::remove_pointer_t<ParserType> &parser() noexcept {
+    if constexpr (std::is_pointer_v<ParserType>) {
+      return *m_parser;
+    } else {
+      return m_parser;
+    }
+  }
+
+  template <typename T>
+  [[nodiscard]] simdjson_inline simdjson_result<T>
+  result() noexcept(is_nothrow_gettable<T>) {
+    if (m_error != SUCCESS) {
+      return m_error;
+    }
+    // For array and object types, we need to be at the start of the document
+    return m_doc.get<T>();
+  }
+
+  [[nodiscard]] simdjson_inline simdjson_result<ondemand::array>
+  array() noexcept {
+    return result<ondemand::array>();
+  }
+
+  [[nodiscard]] simdjson_inline simdjson_result<ondemand::object>
+  object() noexcept {
+    return result<ondemand::object>();
+  }
+
+  [[nodiscard]] simdjson_inline simdjson_result<ondemand::number>
+  number() noexcept {
+    return result<ondemand::number>();
+  }
+
+  template <typename T>
+  [[nodiscard]] simdjson_inline explicit(false)
+  operator simdjson_result<T>() noexcept(is_nothrow_gettable<T>) {
+    return result<T>();
+  }
+
+  template <typename T>
+  [[nodiscard]] simdjson_inline explicit(false) operator T() noexcept(false) {
+    if (m_error != SUCCESS) {
+      throw simdjson_error(m_error);
+    }
+    return m_doc.get<T>();
+  }
+
+  // We can't have "operator std::optional<T>" because it would create an
+  // ambiguity for the compiler.
+  // We also cannot have "operator T*" without manual memory management.
+  // We also cannot have "operator T&" without manual memory management either.
+
+  template <typename T>
+  [[nodiscard]] simdjson_inline std::optional<T>
+  optional() noexcept(is_nothrow_gettable<T>) {
+    if (m_error != SUCCESS) {
+      return std::nullopt;
+    }
+    T value;
+    // For std::optional<T>
+    if (m_doc.get<T>().get(value)) [[unlikely]] {
+      return std::nullopt;
+    }
+    return {std::move(value)};
+  }
+
+  simdjson_inline auto_iterator begin() noexcept {
+    if (m_error != SUCCESS) {
+      // Create an iterator with the error
+      iter_storage.m_iter = iterator::type(m_error);
+      iter_storage.m_value = value_type{};
+      return auto_iterator{iter_storage};
+    }
+    if (iter_storage.m_iter.error() != SUCCESS &&
+        !iter_storage.m_iter.at_end()) {
+      // Try to get the document as an array
+      ondemand::array arr;
+      if(auto error = m_doc.get_array().get(arr); error == SUCCESS) {
+        iter_storage = {.m_iter = iterator::type{arr.begin()},
+                        .m_value = iterator::value_type{
+                            iter_storage.m_iter.at_end() ||
+                                    iter_storage.m_iter.error() != SUCCESS
+                                ? value_type{}
+                                : *iter_storage.m_iter}};
+      } else {
+        // If it's not an array, create an error iterator
+        iter_storage.m_iter = iterator::type(error);
+        iter_storage.m_value = value_type{};
+      }
+    }
+    return auto_iterator{iter_storage};
+  }
+  simdjson_inline auto_iterator_end end() noexcept { return {}; }
+};
+
+#ifdef __cpp_lib_ranges
+
+// For C++20, we implement our own pipe operator since range_adaptor_closure is C++23
+static constexpr struct [[nodiscard]] no_errors_adaptor {
+
+  [[nodiscard]] bool
+  operator()(simdjson_result<ondemand::value> const &val) const noexcept {
+    return val.error() == SUCCESS;
+  }
+
+  template <std::ranges::range Range>
+  auto operator()(Range &&rng) const noexcept {
+    return std::forward<Range>(rng) | std::views::filter(*this);
+  }
+} no_errors;
+
+template <typename T = void>
+struct [[nodiscard]] to_adaptor {
+
+  /// Convert to T
+  [[nodiscard]] T
+  operator()(simdjson_result<ondemand::value> &val) const noexcept {
+    return val.get<T>();
+  }
+
+  /// Make it an adaptor
+  template <std::ranges::range Range>
+  auto operator()(Range &&rng) const noexcept {
+    return std::forward<Range>(rng) | no_errors | std::views::transform(*this);
+  }
+
+  /**
+   * Parse input string into any object if possible.
+   */
+  auto operator()(padded_string_view const str) const noexcept {
+    return auto_parser{str};
+  }
+
+  /**
+   * Parse the input using the specified parser into any object if possible.
+   */
+  auto operator()(ondemand::parser &parser,
+                            padded_string_view const str) const noexcept {
+    return auto_parser<ondemand::parser *>{parser, str};
+  }
+};
+
+template <typename T> static constexpr to_adaptor<T> to{};
+
+static constexpr to_adaptor<> from{};
+
+template <typename T = void>
+using as = to_adaptor<T>;
+
+// For C++20 ranges without range_adaptor_closure, we need to define pipe operators
+template <std::ranges::range Range>
+inline auto operator|(Range&& range, const no_errors_adaptor& adaptor) {
+  return adaptor(std::forward<Range>(range));
+}
+
+template <std::ranges::range Range, typename T>
+inline auto operator|(Range&& range, const to_adaptor<T>& adaptor) {
+  return adaptor(std::forward<Range>(range));
+}
+
+#endif // __cpp_lib_ranges
+
+} // namespace simdjson
+
+#endif // __cpp_concepts
+#endif // SIMDJSON_CONVERT_H

include/simdjson/dom/array-inl.h

@@ -7,6 +7,7 @@
 #include "simdjson/dom/array.h"
 #include "simdjson/dom/element.h"
 #include "simdjson/error-inl.h"
+#include "simdjson/jsonpathutil.h"
 #include "simdjson/internal/tape_ref-inl.h"
 
 #include <limits>
@@ -44,6 +45,13 @@ inline simdjson_result<dom::element> simdjson_result<dom::array>::at_pointer(std
   if (error()) { return error(); }
   return first.at_pointer(json_pointer);
 }
+
+ inline simdjson_result<dom::element> simdjson_result<dom::array>::at_path(std::string_view json_path) const noexcept {
+  auto json_pointer = json_path_to_pointer_conversion(json_path);
+  if (json_pointer == "-1") { return INVALID_JSON_POINTER; }
+  return at_pointer(json_pointer);
+ }
+
 inline simdjson_result<dom::element> simdjson_result<dom::array>::at(size_t index) const noexcept {
   if (error()) { return error(); }
   return first.at(index);
@@ -113,6 +121,12 @@ inline simdjson_result<element> array::at_pointer(std::string_view json_pointer)
   return child;
 }
 
+inline simdjson_result<element> array::at_path(std::string_view json_path) const noexcept {
+  auto json_pointer = json_path_to_pointer_conversion(json_path);
+  if (json_pointer == "-1") { return INVALID_JSON_POINTER; }
+  return at_pointer(json_pointer);
+}
+
 inline simdjson_result<element> array::at(size_t index) const noexcept {
   SIMDJSON_DEVELOPMENT_ASSERT(tape.usable()); // https://github.com/simdjson/simdjson/issues/1914
   size_t i=0;
@@ -123,6 +137,10 @@ inline simdjson_result<element> array::at(size_t index) const noexcept {
   return INDEX_OUT_OF_BOUNDS;
 }
 
+inline array::operator element() const noexcept {
+	return element(tape);
+}
+
 //
 // array::iterator inline implementation
 //

include/simdjson/dom/array.h

@@ -57,7 +57,7 @@ public:
     iterator& operator=(const iterator&) noexcept = default;
   private:
     simdjson_inline iterator(const internal::tape_ref &tape) noexcept;
-    internal::tape_ref tape;
+    internal::tape_ref tape{};
     friend class array;
   };
 
@@ -108,6 +108,21 @@ public:
    */
   inline simdjson_result<element> at_pointer(std::string_view json_pointer) const noexcept;
 
+  /**
+   * Get the value associated with the given JSONPath expression. We only support
+   * JSONPath queries that trivially convertible to JSON Pointer queries: key
+   * names and array indices.
+   *
+   * https://datatracker.ietf.org/doc/html/draft-normington-jsonpath-00
+   *
+   * @return The value associated with the given JSONPath expression, or:
+   *         - INVALID_JSON_POINTER if the JSONPath to JSON Pointer conversion fails
+   *         - NO_SUCH_FIELD if a field does not exist in an object
+   *         - INDEX_OUT_OF_BOUNDS if an array index is larger than an array length
+   *         - INCORRECT_TYPE if a non-integer is used to access an array
+  */
+  inline simdjson_result<element> at_path(std::string_view json_path) const noexcept;
+
   /**
    * Get the value at the given index. This function has linear-time complexity and
    * is equivalent to the following:
@@ -126,9 +141,14 @@ public:
    */
   inline simdjson_result<element> at(size_t index) const noexcept;
 
+  /**
+   * Implicitly convert object to element
+   */
+  inline operator element() const noexcept;
+
 private:
   simdjson_inline array(const internal::tape_ref &tape) noexcept;
-  internal::tape_ref tape;
+  internal::tape_ref tape{};
   friend class element;
   friend struct simdjson_result<element>;
   template<typename T>
@@ -147,6 +167,7 @@ public:
   simdjson_inline simdjson_result(error_code error) noexcept; ///< @private
 
   inline simdjson_result<dom::element> at_pointer(std::string_view json_pointer) const noexcept;
+  inline simdjson_result<dom::element> at_path(std::string_view json_path) const noexcept;
   inline simdjson_result<dom::element> at(size_t index) const noexcept;
 
 #if SIMDJSON_EXCEPTIONS

include/simdjson/dom/document.h

@@ -70,7 +70,7 @@ public:
    * The memory allocation is strict: you
    * can you use this function to increase
    * or lower the amount of allocated memory.
-   * Passsing zero clears the memory.
+   * Passing zero clears the memory.
    */
   error_code allocate(size_t len) noexcept;
   /** @private Capacity in bytes, in terms