3.8.0

* In some cases, clang might try to cast an ondemand::document to an
ondemand::document, instead of calling the move constructor. So we
can disable the template cast.

* In some cases, clang might get confused when constructing an ondemand
document in a constructor: instead of calling the move constructor, it
somehow ends up trying to cast a document to a document. We can easily
disallow this behavior with std::enable_if.

* making compatible with C++11

---------

Co-authored-by: Daniel Lemire <dlemire@lemire.me>

.clangd

@@ -1,5 +1,8 @@
 CompileFlags:
     CompilationDatabase: build
+    Add:
+        - -Werror -Wall -Wextra -Weffc++ -Wsign-compare -Wshadow -Wwrite-strings -Wpointer-arith -Winit-self -Wconversion -Wno-sign-conversion
+        - -Wundefined-inline
 Diagnostics:
     Suppress:
         - misc-unused-alias-decls
@@ -16,10 +19,28 @@ If:
 CompileFlags:
     Add:
         - -Wno-unneeded-internal-declaration
-        - -Wno-undefined-inline # TODO fix and remove these violations
         - -Wno-undefined-internal # TODO fix and remove these violations
         - -Wno-unused-function
         - -Wno-unused-const-variable
 Diagnostics:
     Suppress:
         - pp_including_mainfile_in_preamble
+---
+# Amalgamated files that require or partly define an implementation
+If:
+    PathMatch:
+        - .*/(arm64|fallback|haswell|icelake|ppc64|westmere)/begin.h
+        - .*/generic/.*
+Diagnostics:
+    Suppress:
+        - pragma_attribute_no_pop_eof
+---
+# clang has a bad time detecting the push/pop together in src/ for some reason
+If:
+    PathMatch:
+        - include/simdjson/.*/end.h
+        - src/(arm64|fallback|haswell|icelake|ppc64|westmere).cpp
+Diagnostics:
+    Suppress:
+        - pragma_attribute_no_pop_eof
+        - pragma_attribute_stack_mismatch

.github/ISSUE_TEMPLATE/bug_report.md

@@ -45,11 +45,15 @@ It is fine to report bugs against our main branch, but if that is what you are d
 
 **Configuration (please complete the following information if relevant)**
  - OS: [e.g. Ubuntu 16.04.6 LTS]
- - Compiler [e.g. Apple clang version 11.0.3 (clang-1103.0.32.59) x86_64-apple-darwin19.4.0]
+ - Compiler* [e.g. Apple clang version 11.0.3 (clang-1103.0.32.59) x86_64-apple-darwin19.4.0]
  - Version [e.g. 22]
  - Optimization setting (e.g., -O3)
 
-We support up-to-date 64-bit ARM and x64 FreeBSD, macOS, Windows and Linux systems. Please ensure that your configuration is supported before labelling the issue as a bug. In particular, we do not support legacy 32-bit systems.
+We support up-to-date 64-bit ARM and x64 FreeBSD, macOS, Windows and Linux systems. Please ensure that your configuration is supported before labelling the issue as a bug.
+
+* We do not support unreleased or experimental compilers. If you encounter an issue with a
+pre-release version of a compiler, do not report it as a bug to simdjson. However, we always
+invite contributions either in the form an analysis or of a code contribution.
 
 **Indicate whether you are willing or able to provide a bug fix as a pull request**
 

.github/ISSUE_TEMPLATE/feature_request.md

@@ -31,7 +31,7 @@ A clear and concise description of any alternative solutions or features you've
 **Additional context**
 Add any other context or screenshots about the feature request here.
 
-** Are you willing to contribute code or documentation toward this new feature? **
+**Are you willing to contribute code or documentation toward this new feature?**
 If you plan to contribute to simdjson, please read our
 * CONTRIBUTING guide: https://github.com/simdjson/simdjson/blob/master/CONTRIBUTING.md and our
 * HACKING guide: https://github.com/simdjson/simdjson/blob/master/HACKING.md

.github/workflows/alpine.yml

@@ -9,7 +9,7 @@ jobs:
       ! contains(toJSON(github.event.commits.*.message), '[skip github]')
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: actions/cache@v3
         with:
           path: dependencies/.cache

.github/workflows/debian.yaml

@@ -16,7 +16,7 @@ jobs:
       image: debian:testing
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
 
     - name: Install dependencies
       run: |

.github/workflows/documentation.yml

@@ -19,7 +19,7 @@ jobs:
       url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Install Doxygen
         run: sudo apt-get install doxygen graphviz -y
       - run: mkdir docs

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

@@ -6,7 +6,7 @@ jobs:
   whitespace:
     runs-on: ubuntu-20.04
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Remove whitespace and check the diff
         run: |
           set -eu

.github/workflows/fuzzers.yml

@@ -34,10 +34,11 @@ jobs:
         sudo apt update
         sudo apt-get install --quiet ninja-build valgrind zip unzip lsb-release wget software-properties-common gnupg
         wget https://apt.llvm.org/llvm.sh
+        sudo apt-get purge --auto-remove llvm python3-lldb-14 llvm-14
         chmod +x llvm.sh
         sudo ./llvm.sh $CLANGVERSION
 
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
 
     - uses: actions/cache@v3
       with:

.github/workflows/macos.yml

@@ -9,7 +9,7 @@ jobs:
       ! contains(toJSON(github.event.commits.*.message), '[skip github]')
     runs-on: macos-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: actions/cache@v3
         with:
           path: dependencies/.cache
@@ -31,3 +31,14 @@ jobs:
           echo -e '#include <simdjson.h>\nint main(int argc,char**argv) {simdjson::dom::parser parser;simdjson::dom::element tweets = parser.load(argv[1]); }' > tmp.cpp && c++ -Idestination/include -Ldestination/lib -std=c++17 -Wl,-rpath,destination/lib -o linkandrun tmp.cpp -lsimdjson && ./linkandrun jsonexamples/twitter.json &&
           cd ../tests/installation_tests/find &&
           mkdir build && cd build && cmake -DCMAKE_INSTALL_PREFIX:PATH=../../../build/destination .. &&  cmake --build .
+      - name: Use cmake (shared)
+        run: |
+          mkdir buildshared &&
+          cd buildshared &&
+          cmake  -DSIMDJSON_GOOGLE_BENCHMARKS=ON -DSIMDJSON_DEVELOPER_MODE=ON -DBUILD_SHARED_LIBS=ON -DCMAKE_INSTALL_PREFIX:PATH=destination ..  &&
+          cmake --build .   &&
+          ctest --output-on-failure -LE explicitonly -j   &&
+          cmake --install . &&
+          echo -e '#include <simdjson.h>\nint main(int argc,char**argv) {simdjson::dom::parser parser;simdjson::dom::element tweets = parser.load(argv[1]); }' > tmp.cpp && c++ -Idestination/include -Ldestination/lib -std=c++17 -Wl,-rpath,destination/lib -o linkandrun tmp.cpp -lsimdjson && ./linkandrun jsonexamples/twitter.json &&
+          cd ../tests/installation_tests/find &&
+          mkdir buildshared && cd buildshared && cmake -DCMAKE_INSTALL_PREFIX:PATH=../../../buildshared/destination .. &&  cmake --build .

.github/workflows/msys2-clang.yml

@@ -24,7 +24,7 @@ jobs:
       CMAKE_GENERATOR: Ninja
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: actions/cache@v3
         with:
           path: dependencies/.cache

.github/workflows/msys2.yml

@@ -26,7 +26,7 @@ jobs:
       CMAKE_GENERATOR: Ninja
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: actions/cache@v3
         with:
           path: dependencies/.cache

.github/workflows/power-fuzz.yml

@@ -15,7 +15,7 @@ jobs:
     runs-on: ubuntu-20.04
     name: Build on ubuntu-20.04 ppc64le
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: uraimo/run-on-arch-action@v2.0.5
         name: Run commands
         id: runcmd

.github/workflows/ppc64.yml

@@ -12,7 +12,7 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: uraimo/run-on-arch-action@v2
         name: Test
         id: runcmd

.github/workflows/riscv64.yml

@@ -0,0 +1,29 @@
+name: Ubuntu riscv64 (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@v2
+        name: Test
+        id: runcmd
+        with:
+          arch: riscv64
+          distro: ubuntu_latest
+          githubToken: ${{ github.token }}
+          install: |
+            apt-get update -q -y
+            apt-get install -y cmake make g++
+          run: |
+            cmake -DCMAKE_BUILD_TYPE=Release -B build
+            cmake --build build -j=2
+            ctest --output-on-failure --test-dir build

.github/workflows/s390x.yml

@@ -12,7 +12,7 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: uraimo/run-on-arch-action@v2
         name: Test
         id: runcmd

.github/workflows/ubuntu20-checkperf.yml

@@ -15,7 +15,7 @@ jobs:
       ! contains(toJSON(github.event.commits.*.message), '[skip github]')
     runs-on: ubuntu-20.04
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: actions/cache@v3
         with:
           path: dependencies/.cache

.github/workflows/ubuntu20-gcc8.yml

@@ -12,7 +12,7 @@ jobs:
       CXX: g++-8
       CC: gcc-8
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: actions/cache@v3
         with:
           path: dependencies/.cache

.github/workflows/ubuntu20-noexcept.yml

@@ -9,7 +9,7 @@ jobs:
       ! contains(toJSON(github.event.commits.*.message), '[skip github]')
     runs-on: ubuntu-20.04
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: actions/cache@v3
         with:
           path: dependencies/.cache

.github/workflows/ubuntu20-nothread.yml

@@ -9,7 +9,7 @@ jobs:
       ! contains(toJSON(github.event.commits.*.message), '[skip github]')
     runs-on: ubuntu-20.04
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: actions/cache@v3
         with:
           path: dependencies/.cache

.github/workflows/ubuntu20-sani.yml

@@ -3,13 +3,13 @@ name: Ubuntu 20.04 CI (GCC 9) With Memory Sanitizer
 on: [push, pull_request]
 
 jobs:
-  ubuntu-build:
+  ubuntu-build-address-sanitizier:
     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@v3
+      - uses: actions/checkout@v4
       - uses: actions/cache@v3
         with:
           path: dependencies/.cache
@@ -21,6 +21,17 @@ jobs:
           cmake -DSIMDJSON_SANITIZE=ON -DCMAKE_BUILD_TYPE=Debug -DSIMDJSON_GOOGLE_BENCHMARKS=OFF -DSIMDJSON_DEVELOPER_MODE=ON -DBUILD_SHARED_LIBS=OFF ..  &&
           cmake --build .   &&
           ctest --output-on-failure -LE explicitonly -j
+  ubuntu-build-undefined-sanitizer:
+    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@v3
+        with:
+          path: dependencies/.cache
+          key: ${{ hashFiles('dependencies/CMakeLists.txt') }}
       - name: Use cmake with undefined sanitizer
         run: |
           mkdir builddebugundefsani &&

.github/workflows/ubuntu20.yml

@@ -9,11 +9,25 @@ jobs:
       ! contains(toJSON(github.event.commits.*.message), '[skip github]')
     runs-on: ubuntu-20.04
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: actions/cache@v3
         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 &&

.github/workflows/ubuntu22-clang13.yml

@@ -9,13 +9,11 @@ jobs:
       ! contains(toJSON(github.event.commits.*.message), '[skip github]')
     runs-on: ubuntu-22.04
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: actions/cache@v3
         with:
           path: dependencies/.cache
           key: ${{ hashFiles('dependencies/CMakeLists.txt') }}
-      - name: Install clang++-13
-        run: sudo apt-get install -y clang++-13
       - name: Use cmake
         run: |
           mkdir build &&

.github/workflows/ubuntu22-clang14.yml

@@ -9,13 +9,11 @@ jobs:
       ! contains(toJSON(github.event.commits.*.message), '[skip github]')
     runs-on: ubuntu-22.04
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: actions/cache@v3
         with:
           path: dependencies/.cache
           key: ${{ hashFiles('dependencies/CMakeLists.txt') }}
-      - name: Install clang++-14
-        run: sudo apt-get install -y clang++-14
       - name: Use cmake
         run: |
           mkdir build &&

.github/workflows/ubuntu22-cxx20.yml

@@ -9,7 +9,7 @@ jobs:
       ! contains(toJSON(github.event.commits.*.message), '[skip github]')
     runs-on: ubuntu-22.04
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: actions/cache@v3
         with:
           path: dependencies/.cache

.github/workflows/ubuntu22-gcc12.yml

@@ -9,13 +9,11 @@ jobs:
       ! contains(toJSON(github.event.commits.*.message), '[skip github]')
     runs-on: ubuntu-22.04
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: actions/cache@v3
         with:
           path: dependencies/.cache
           key: ${{ hashFiles('dependencies/CMakeLists.txt') }}
-      - name: Install gcc12
-        run: sudo apt-get install -y g++-12
       - name: Use cmake
         run: |
           mkdir build &&

.github/workflows/ubuntu22-gcc13.yml

@@ -0,0 +1,23 @@
+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@v3
+        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/ubuntu22-glibcxxassertions.yml

@@ -8,7 +8,7 @@ jobs:
       ! contains(toJSON(github.event.commits.*.message), '[skip github]')
     runs-on: ubuntu-22.04
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: actions/cache@v3
         with:
           path: dependencies/.cache

.github/workflows/ubuntu22-threadsani.yml

@@ -1,4 +1,4 @@
-name: Ubuntu 20.04 CI (GCC 9) with Thread Sanitizer
+name: Ubuntu 22.04 CI (GCC 11) with Thread Sanitizer
 
 on: [push, pull_request]
 
@@ -7,9 +7,9 @@ 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-22.04
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: actions/cache@v3
         with:
           path: dependencies/.cache

.github/workflows/ubuntu22.yml

@@ -9,11 +9,25 @@ jobs:
       ! contains(toJSON(github.event.commits.*.message), '[skip github]')
     runs-on: ubuntu-22.04
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: actions/cache@v3
         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 &&

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

@@ -14,7 +14,7 @@ jobs:
            - {arch: ARM64}
      steps:
        - name: checkout
-         uses: actions/checkout@v3
+         uses: actions/checkout@v4
        - name: Use cmake
          run: |
            cmake -A ${{ matrix.arch }} -DCMAKE_CROSSCOMPILING=1 -DSIMDJSON_DEVELOPER_MODE=ON -D SIMDJSON_GOOGLE_BENCHMARKS=OFF -DSIMDJSON_EXCEPTIONS=OFF -B build  &&

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

@@ -19,7 +19,7 @@ jobs:
           - {gen: Visual Studio 17 2022, arch: x64, shared: OFF}
     steps:
     - name: checkout
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
     - name: Configure
       run: |
         cmake -DSIMDJSON_CXX_STANDARD=20 -G "${{matrix.gen}}" -A ${{matrix.arch}} -DSIMDJSON_DEVELOPER_MODE=ON -DSIMDJSON_COMPETITION=OFF -DBUILD_SHARED_LIBS=${{matrix.shared}} -B build

.github/workflows/vs17-ci.yml

@@ -19,7 +19,7 @@ jobs:
           - {gen: Visual Studio 17 2022, arch: x64, shared: OFF}
     steps:
     - name: checkout
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
     - name: Configure
       run: |
         cmake -G "${{matrix.gen}}" -A ${{matrix.arch}} -DSIMDJSON_DEVELOPER_MODE=ON -DSIMDJSON_COMPETITION=OFF -DBUILD_SHARED_LIBS=${{matrix.shared}} -B build

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

@@ -16,7 +16,7 @@ jobs:
           - {gen: Visual Studio 17 2022, arch: x64}
     steps:
     - name: checkout
-      uses: actions/checkout@v3
+      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

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

@@ -7,7 +7,7 @@ jobs:
     name: windows-vs17
     runs-on: windows-latest
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - uses: actions/cache@v3
       with:
         path: dependencies/.cache

.vscode/settings.json

@@ -98,6 +98,17 @@
         "queue": "cpp",
         "shared_mutex": "cpp",
         "ranges": "cpp",
-        "span": "cpp"
+        "span": "cpp",
+        "__verbose_abort": "cpp",
+        "charconv": "cpp",
+        "source_location": "cpp",
+        "strstream": "cpp",
+        "typeindex": "cpp",
+        "*.tcc": "cpp",
+        "memory_resource": "cpp",
+        "numbers": "cpp",
+        "semaphore": "cpp",
+        "stop_token": "cpp",
+        "cfenv": "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.2.1
+    VERSION 3.8.0
     DESCRIPTION "Parsing gigabytes of JSON per second"
     HOMEPAGE_URL "https://simdjson.org/"
     LANGUAGES CXX C
@@ -20,8 +20,10 @@ string(
 # ---- Options, variables ----
 
 # These version numbers are modified by tools/release.py
-set(SIMDJSON_LIB_VERSION "16.0.0" CACHE STRING "simdjson library version")
-set(SIMDJSON_LIB_SOVERSION "16" CACHE STRING "simdjson library soversion")
+set(SIMDJSON_LIB_VERSION "21.0.0" CACHE STRING "simdjson library version")
+set(SIMDJSON_LIB_SOVERSION "21" CACHE STRING "simdjson library soversion")
+
+option(SIMDJSON_BUILD_STATIC_LIB "Build simdjson_static library along with simdjson" OFF)
 
 option(SIMDJSON_ENABLE_THREADS "Link with thread support" ON)
 
@@ -56,8 +58,17 @@ include(cmake/developer-options.cmake)
 
 # ---- simdjson library ----
 
-add_library(simdjson src/simdjson.cpp)
+set(SIMDJSON_SOURCES src/simdjson.cpp)
+
+add_library(simdjson ${SIMDJSON_SOURCES})
 add_library(simdjson::simdjson ALIAS simdjson)
+set(SIMDJSON_LIBRARIES simdjson)
+
+if(SIMDJSON_BUILD_STATIC_LIB)
+  add_library(simdjson_static STATIC ${SIMDJSON_SOURCES})
+  add_library(simdjson::simdjson_static ALIAS simdjson_static)
+  list(APPEND SIMDJSON_LIBRARIES simdjson_static)
+endif()
 
 set_target_properties(
     simdjson PROPERTIES
@@ -117,6 +128,9 @@ if(SIMDJSON_ENABLE_THREADS)
 endif()
 
 simdjson_apply_props(simdjson)
+if(SIMDJSON_BUILD_STATIC_LIB)
+  simdjson_apply_props(simdjson_static)
+endif()
 
 # ---- Install rules ----
 
@@ -138,7 +152,6 @@ install(
     ARCHIVE COMPONENT simdjson_Development
     INCLUDES DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}"
 )
-
 configure_file(cmake/simdjson-config.cmake.in simdjson-config.cmake @ONLY)
 
 write_basic_package_version_file(
@@ -167,6 +180,20 @@ install(
     COMPONENT simdjson_Development
 )
 
+if(SIMDJSON_BUILD_STATIC_LIB)
+  install(
+      TARGETS simdjson_static
+      EXPORT simdjson_staticTargets
+      ARCHIVE COMPONENT simdjson_Development
+  )
+  install(
+      EXPORT simdjson_staticTargets
+      NAMESPACE simdjson::
+      DESTINATION "${SIMDJSON_INSTALL_CMAKEDIR}"
+      COMPONENT simdjson_Development
+  )
+endif()
+
 # pkg-config
 include(cmake/JoinPaths.cmake)
 join_paths(PKGCONFIG_INCLUDEDIR "\${prefix}" "${CMAKE_INSTALL_INCLUDEDIR}")

CONTRIBUTING.md

@@ -52,10 +52,11 @@ General Guidelines
 Contributors are encouraged to :
 
 - Document their changes. Though we do not enforce a rule regarding code comments, we prefer that non-trivial algorithms and techniques be somewhat documented in the code.
-- Follow as much as possible the existing code style. We do not enforce a specific code style, but we prefer consistency.
+- Follow as much as possible the existing code style. We do not enforce a specific code style, but we prefer consistency. We avoid contractions (isn't, aren't) in the comments.
 - Modify as few lines of code as possible when working on an issue. The more lines you modify, the harder it is for your fellow human beings to understand what is going on.
 - Tools may report "problems" with the code, but we never delegate programming to tools: if there is a problem with the code, we need to understand it. Thus we will not "fix" code merely to please a static analyzer.
 - Provide tests for any new feature. We will not merge a new feature without tests.
+- Run before/after benchmarks so that we can appreciate the effect of the changes on the performance.
 
 Pull Requests
 --------------

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.2.1"
+PROJECT_NUMBER         = "3.8.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

@@ -80,7 +80,7 @@ simdjson's source structure, from the top level, looks like this:
     * simdjson/internal/*.h: the `simdjson::internal` namespace. Private classes and functions used by the rest of simdjson.
   * simdjson/dom.h: the `simdjson::dom` namespace. Includes all public DOM classes.
     * simdjson/dom/*.h: Declarations/definitions for individual DOM classes.
-  * simdjson/arm64|fallback|haswell|icelake|ppc64|westmere.h: `simdjson::<implementation>` namesapce. Common implementation-specific tools like number and string parsing, as well as minification.
+  * simdjson/arm64|fallback|haswell|icelake|ppc64|westmere.h: `simdjson::<implementation>` namespace. Common implementation-specific tools like number and string parsing, as well as minification.
     * simdjson/arm64|fallback|haswell|icelake|ppc64|westmere/*.h: implementation-specific functions such as , etc.
     * simdjson/generic/*.h: the bulk of the actual code, written generically and compiled for each implementation, using functions defined in the implementation's .h files.
       * simdjson/generic/dependencies.h: dependencies on common, non-implementation-specific simdjson classes. This will be included before including amalgamated.h.
@@ -283,8 +283,6 @@ If your compiler does not default on C++11 support or better you may get failing
 
 Note that the name of directory (`build`) is arbitrary, you can name it as you want (e.g., `buildgcc`) and you can have as many different such directories as you would like (one per configuration).
 
-
-
 ## Usage (CMake on 64-bit Windows using Visual Studio 2019 or better)
 
 Recent versions of Visual Studio support CMake natively, [please refer to the Visual Studio documentation](https://learn.microsoft.com/en-us/cpp/build/cmake-projects-in-visual-studio?view=msvc-170).
@@ -304,17 +302,15 @@ Though having Visual Studio installed is necessary, one can build simdjson using
 - `mkdir build`
 - `cd build`
 - `cmake ..`
-- `cmake --build . -config Release`
+- `cmake --build . --config Release`
 
 
 Furthermore, if you have installed LLVM clang on Windows, for example as a component of Visual Studio 2019, you can configure and build simdjson using LLVM clang on Windows using cmake:
 
-
 - `mkdir build`
 - `cd build`
 - `cmake -T ClangCL ..`
-- `cmake --build . -config Release`
-
+- `cmake --build . --config Release`
 
 ## Various References
 

README.md

@@ -1,8 +1,6 @@
 
 [![Ubuntu 20.04 CI](https://github.com/simdjson/simdjson/workflows/Ubuntu%2020.04%20CI%20(GCC%209)/badge.svg)](https://simdjson.org/plots.html)
-![VS16-CI](https://github.com/simdjson/simdjson/workflows/VS16-CI/badge.svg)
 [![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)
-![MinGW64-CI](https://github.com/simdjson/simdjson/workflows/MinGW64-CI/badge.svg)
 [![][license img]][license]
 
 [![Doxygen Documentation](https://img.shields.io/badge/docs-doxygen-green.svg)](https://simdjson.github.io/simdjson/)
@@ -31,6 +29,7 @@ Table of Contents
 * [Real-world usage](#real-world-usage)
 * [Quick Start](#quick-start)
 * [Documentation](#documentation)
+* [Godbolt](#godbolt)
 * [Performance results](#performance-results)
 * [Bindings and Ports of simdjson](#bindings-and-ports-of-simdjson)
 * [About simdjson](#about-simdjson)
@@ -42,8 +41,10 @@ Table of Contents
 Real-world usage
 ----------------
 
+- [Node.js](https://nodejs.org/)
 - [ClickHouse](https://github.com/ClickHouse/ClickHouse)
-- [Facebook/Meta Velox](https://velox-lib.io)
+- [Meta Velox](https://velox-lib.io)
+- [Google Pax](https://github.com/google/paxml)
 - [milvus](https://github.com/milvus-io/milvus)
 - [Clang Build Analyzer](https://github.com/aras-p/ClangBuildAnalyzer)
 - [Shopify HeapProfiler](https://github.com/Shopify/heap-profiler)
@@ -68,9 +69,9 @@ The simdjson library is easily consumable with a single .h and .cpp file.
 
 0. Prerequisites: `g++` (version 7 or better) or `clang++` (version 6 or better), and a 64-bit
    system with a command-line shell (e.g., Linux, macOS, freeBSD). We also support programming
-   environments like Visual Studio and Xcode, but different steps are needed.
+   environments like Visual Studio and Xcode, but different steps are needed. Users of clang++ may need to specify the C++ version (e.g., `c++ -std=c++17`) since clang++ tends to default on C++98.
 1. Pull [simdjson.h](singleheader/simdjson.h) and [simdjson.cpp](singleheader/simdjson.cpp) into a
-   directory, along with the sample file [twitter.json](jsonexamples/twitter.json).
+   directory, along with the sample file [twitter.json](jsonexamples/twitter.json). You can download them with the `wget` utility:
 
    ```
    wget https://raw.githubusercontent.com/simdjson/simdjson/master/singleheader/simdjson.h https://raw.githubusercontent.com/simdjson/simdjson/master/singleheader/simdjson.cpp https://raw.githubusercontent.com/simdjson/simdjson/master/jsonexamples/twitter.json
@@ -95,6 +96,7 @@ int main(void) {
    100 results.
   ```
 
+
 Documentation
 -------------
 
@@ -106,11 +108,12 @@ Usage documentation is available:
   how you can work with it.
 * [API](https://simdjson.github.io/simdjson/) contains the automatically generated API documentation.
 
+Godbolt
+-------------
 
 Some users may want to browse code along with the compiled assembly. You want to check out the following lists of examples:
-
-* [simdjson examples with errors handled through exceptions](https://godbolt.org/z/98Kx9Kqjn)
-* [simdjson examples with errors without exceptions](https://godbolt.org/z/PKG7GdbPo)
+* [simdjson examples with errors handled through exceptions](https://godbolt.org/z/7G5qE4sr9)
+* [simdjson examples with errors without exceptions](https://godbolt.org/z/e9dWb9E4v)
 
 Performance results
 -------------------
@@ -165,6 +168,8 @@ We distinguish between "bindings" (which just wrap the C++ code) and a port to a
 - [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.
+- [simdjson-java](https://github.com/simdjson/simdjson-java): Java port.
 
 About simdjson
 --------------
@@ -173,7 +178,11 @@ 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.
 
-Some people [enjoy reading our paper](https://arxiv.org/abs/1902.08318): A description of the design
+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 (to appear)
+
+Some people [enjoy reading the first (2019) simdjson paper](https://arxiv.org/abs/1902.08318): A description of the design
 and implementation of simdjson is in our research article:
 - Geoff Langdale, Daniel Lemire, [Parsing Gigabytes of JSON per Second](https://arxiv.org/abs/1902.08318), VLDB Journal 28 (6), 2019.
 

SECURITY.md

@@ -0,0 +1,7 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+Please use the following contact information for reporting a vulnerability:
+
+- [Daniel Lemire](https://github.com/lemire) - daniel@lemire.me

benchmark/CMakeLists.txt

@@ -26,6 +26,9 @@ if (TARGET benchmark::benchmark)
     if(TARGET nlohmann_json)
       target_link_libraries(bench_ondemand PRIVATE nlohmann_json)
     endif()
+    if(TARGET boostjson)
+      target_link_libraries(bench_ondemand PRIVATE boostjson)
+    endif()
   endif()
 endif()
 

benchmark/bench_dom_api.cpp

@@ -473,28 +473,6 @@ static void twitter_count(State& state) {
 }
 BENCHMARK(twitter_count);
 
-#ifndef SIMDJSON_DISABLE_DEPRECATED_API
-SIMDJSON_PUSH_DISABLE_WARNINGS
-SIMDJSON_DISABLE_DEPRECATED_WARNING
-static void iterator_twitter_count(State& state) {
-  // Prints the number of results in twitter.json
-  padded_string json = padded_string::load(TWITTER_JSON);
-  ParsedJson pj = build_parsed_json(json);
-  for (simdjson_unused auto _ : state) {
-    ParsedJson::Iterator iter(pj);
-    // uint64_t result_count = doc["search_metadata"]["count"];
-    if (!iter.move_to_key("search_metadata")) { return; }
-    if (!iter.move_to_key("count")) { return; }
-    if (!iter.is_integer()) { return; }
-    int64_t result_count = iter.get_integer();
-
-    if (result_count != 100) { return; }
-  }
-}
-BENCHMARK(iterator_twitter_count);
-SIMDJSON_POP_DISABLE_WARNINGS
-#endif // SIMDJSON_DISABLE_DEPRECATED_API
-
 static void twitter_default_profile(State& state) {
   // Count unique users with a default profile.
   dom::parser parser;
@@ -578,54 +556,6 @@ static void error_code_twitter_default_profile(State& state) noexcept {
 }
 BENCHMARK(error_code_twitter_default_profile);
 
-#ifndef SIMDJSON_DISABLE_DEPRECATED_API
-
-SIMDJSON_PUSH_DISABLE_WARNINGS
-SIMDJSON_DISABLE_DEPRECATED_WARNING
-
-static void iterator_twitter_default_profile(State& state) {
-  // Count unique users with a default profile.
-  padded_string json;
-  auto error = padded_string::load(TWITTER_JSON).get(json);
-  if (error) { std::cerr << error << std::endl; return; }
-  ParsedJson pj = build_parsed_json(json);
-  for (simdjson_unused auto _ : state) {
-    set<string_view> default_users;
-    ParsedJson::Iterator iter(pj);
-
-    // for (dom::object tweet : doc["statuses"]) {
-    if (!(iter.move_to_key("statuses") && iter.is_array())) { return; }
-    if (iter.down()) { // first status
-      do {
-
-        // dom::object user = tweet["user"];
-        if (!(iter.move_to_key("user") && iter.is_object())) { return; }
-
-        // if (user["default_profile"]) {
-        if (iter.move_to_key("default_profile")) {
-          if (iter.is_true()) {
-            if (!iter.up()) { return; } // back to user
-
-            // default_users.insert(user["screen_name"]);
-            if (!(iter.move_to_key("screen_name") && iter.is_string())) { return; }
-            default_users.emplace(iter.get_string(), iter.get_string_length());
-          }
-          if (!iter.up()) { return; } // back to user
-        }
-
-        if (!iter.up()) { return; } // back to status
-
-      } while (iter.next()); // next status
-    }
-
-    if (default_users.size() != 86) { return; }
-  }
-}
-
-SIMDJSON_POP_DISABLE_WARNINGS
-BENCHMARK(iterator_twitter_default_profile);
-#endif // SIMDJSON_DISABLE_DEPRECATED_API
-
 static void error_code_twitter_image_sizes(State& state) noexcept {
   // Count unique image sizes
   dom::parser parser;
@@ -680,92 +610,4 @@ static void parse_surrogate_pairs(State& state) {
 }
 BENCHMARK(parse_surrogate_pairs);
 
-
-#ifndef SIMDJSON_DISABLE_DEPRECATED_API
-
-SIMDJSON_PUSH_DISABLE_WARNINGS
-SIMDJSON_DISABLE_DEPRECATED_WARNING
-static void iterator_twitter_image_sizes(State& state) {
-  // Count unique image sizes
-  padded_string json;
-  auto error = padded_string::load(TWITTER_JSON).get(json);
-  if (error) { std::cerr << error << std::endl; return; }
-  ParsedJson pj = build_parsed_json(json);
-  for (simdjson_unused auto _ : state) {
-    set<tuple<uint64_t, uint64_t>> image_sizes;
-    ParsedJson::Iterator iter(pj);
-
-    // for (dom::object tweet : doc["statuses"]) {
-    if (!(iter.move_to_key("statuses") && iter.is_array())) { return; }
-    if (iter.down()) { // first status
-      do {
-
-        // dom::object media;
-        // not_found = tweet["entities"]["media"].get(media);
-        // if (!not_found) {
-        if (iter.move_to_key("entities")) {
-          if (!iter.is_object()) { return; }
-          if (iter.move_to_key("media")) {
-            if (!iter.is_array()) { return; }
-
-            //   for (dom::object image : media) {
-            if (iter.down()) { // first media
-              do {
-
-                // for (auto [key, size] : dom::object(image["sizes"])) {
-                if (!(iter.move_to_key("sizes") && iter.is_object())) { return; }
-                if (iter.down()) { // first size
-                  do {
-                    iter.move_to_value();
-
-                    // image_sizes.insert({ size["w"], size["h"] });
-                    if (!(iter.move_to_key("w")) && !iter.is_integer()) { return; }
-                    uint64_t width = iter.get_integer();
-                    if (!iter.up()) { return; } // back to size
-                    if (!(iter.move_to_key("h")) && !iter.is_integer()) { return; }
-                    uint64_t height = iter.get_integer();
-                    if (!iter.up()) { return; } // back to size
-                    image_sizes.emplace(width, height);
-
-                  } while (iter.next()); // next size
-                  if (!iter.up()) { return; } // back to sizes
-                }
-                if (!iter.up()) { return; } // back to image
-              } while (iter.next()); // next image
-              if (!iter.up()) { return; } // back to media
-            }
-            if (!iter.up()) { return; } // back to entities
-          }
-          if (!iter.up()) { return; } // back to status
-        }
-      } while (iter.next()); // next status
-    }
-
-    if (image_sizes.size() != 15) { return; };
-  }
-}
-BENCHMARK(iterator_twitter_image_sizes);
-
-#endif // SIMDJSON_DISABLE_DEPRECATED_API
-
-#ifndef SIMDJSON_DISABLE_DEPRECATED_API
-static void print_json(State& state) noexcept {
-  // Prints the number of results in twitter.json
-  dom::parser parser;
-
-  padded_string json;
-  auto error = padded_string::load(TWITTER_JSON).get(json);
-  if (error) { std::cerr << error << std::endl; return; }
-
-  int code = json_parse(json, parser);
-  if (code) { cerr << error_message(code) << endl; return; }
-  for (simdjson_unused auto _ : state) {
-    std::stringstream s;
-    if (!parser.print_json(s)) { cerr << "print_json failed" << endl; return; }
-  }
-}
-BENCHMARK(print_json);
-#endif // SIMDJSON_DISABLE_DEPRECATED_API
-SIMDJSON_POP_DISABLE_WARNINGS
-
 BENCHMARK_MAIN();

benchmark/bench_ondemand.cpp

@@ -21,6 +21,10 @@ SIMDJSON_PUSH_DISABLE_ALL_WARNINGS
 #include <nlohmann/json.hpp>
 #endif
 
+#ifdef SIMDJSON_COMPETITION_BOOSTJSON
+#include <boost/json.hpp>
+#endif
+
 // This has to be last, for reasons I don't yet understand
 #include <benchmark/benchmark.h>
 
@@ -33,6 +37,7 @@ SIMDJSON_POP_DISABLE_WARNINGS
 #include "json2msgpack/sajson.h"
 #endif // SIMDJSON_COMPETITION_ONDEMAND_SAJSON
 #include "json2msgpack/nlohmann_json.h"
+#include "json2msgpack/boostjson.h"
 
 #include "partial_tweets/simdjson_ondemand.h"
 #include "partial_tweets/simdjson_dom.h"
@@ -48,6 +53,7 @@ SIMDJSON_POP_DISABLE_WARNINGS
 #if SIMDJSON_COMPETITION_SAX
 #include "partial_tweets/nlohmann_json_sax.h"
 #endif // SIMDJSON_COMPETITION_SAX
+#include "partial_tweets/boostjson.h"
 
 
 #include "distinct_user_id/simdjson_ondemand.h"
@@ -66,6 +72,7 @@ SIMDJSON_POP_DISABLE_WARNINGS
 #if SIMDJSON_COMPETITION_SAX
 #include "distinct_user_id/nlohmann_json_sax.h"
 #endif // SIMDJSON_COMPETITION_SAX
+#include "distinct_user_id/boostjson.h"
 
 #include "find_tweet/simdjson_ondemand.h"
 #include "find_tweet/simdjson_dom.h"
@@ -81,6 +88,7 @@ SIMDJSON_POP_DISABLE_WARNINGS
 #if SIMDJSON_COMPETITION_SAX
 #include "find_tweet/nlohmann_json_sax.h"
 #endif // SIMDJSON_COMPETITION_SAX
+#include "find_tweet/boostjson.h"
 
 #include "top_tweet/simdjson_ondemand.h"
 #include "top_tweet/simdjson_dom.h"
@@ -96,6 +104,7 @@ SIMDJSON_POP_DISABLE_WARNINGS
 #if SIMDJSON_COMPETITION_SAX
 #include "top_tweet/nlohmann_json_sax.h"
 #endif // SIMDJSON_COMPETITION_SAX
+#include "top_tweet/boostjson.h"
 
 
 #include "kostya/simdjson_ondemand.h"
@@ -112,6 +121,7 @@ SIMDJSON_POP_DISABLE_WARNINGS
 #if SIMDJSON_COMPETITION_SAX
 #include "kostya/nlohmann_json_sax.h"
 #endif // SIMDJSON_COMPETITION_SAX
+#include "kostya/boostjson.h"
 
 #include "large_random/simdjson_ondemand.h"
 #if SIMDJSON_COMPETITION_ONDEMAND_UNORDERED
@@ -130,6 +140,7 @@ SIMDJSON_POP_DISABLE_WARNINGS
 #if SIMDJSON_COMPETITION_SAX
 #include "large_random/nlohmann_json_sax.h"
 #endif // SIMDJSON_COMPETITION_SAX
+#include "large_random/boostjson.h"
 
 #include "amazon_cellphones/simdjson_dom.h"
 #include "amazon_cellphones/simdjson_ondemand.h"

benchmark/bench_parse_call.cpp

@@ -169,22 +169,6 @@ BENCHMARK(parse_gsoc)->Repetitions(10)->ComputeStatistics("max", [](const std::v
   })->DisplayAggregatesOnly(true);
 
 
-
-#ifndef SIMDJSON_DISABLE_DEPRECATED_API
-SIMDJSON_PUSH_DISABLE_WARNINGS
-SIMDJSON_DISABLE_DEPRECATED_WARNING
-static void json_parse(State& state) {
-  ParsedJson pj;
-  if (!pj.allocate_capacity(EMPTY_ARRAY.length())) { return; }
-  for (simdjson_unused auto _ : state) {
-    auto error = json_parse(EMPTY_ARRAY, pj);
-    if (error) { return; }
-  }
-}
-SIMDJSON_POP_DISABLE_WARNINGS
-BENCHMARK(json_parse);
-#endif // SIMDJSON_DISABLE_DEPRECATED_API
-
 static void parser_parse_error_code(State& state) {
   dom::parser parser;
   if (parser.allocate(EMPTY_ARRAY.length())) { return; }
@@ -213,20 +197,6 @@ BENCHMARK(parser_parse_exception);
 
 #endif // SIMDJSON_EXCEPTIONS
 
-#ifndef SIMDJSON_DISABLE_DEPRECATED_API
-SIMDJSON_PUSH_DISABLE_WARNINGS
-SIMDJSON_DISABLE_DEPRECATED_WARNING
-static void build_parsed_json(State& state) {
-  for (simdjson_unused auto _ : state) {
-    dom::parser parser = simdjson::build_parsed_json(EMPTY_ARRAY);
-    if (!parser.valid) { return; }
-  }
-}
-SIMDJSON_POP_DISABLE_WARNINGS
-
-BENCHMARK(build_parsed_json);
-#endif
-
 static void document_parse_error_code(State& state) {
   for (simdjson_unused auto _ : state) {
     dom::parser parser;

benchmark/benchmarker.h

@@ -445,7 +445,7 @@ struct benchmarker {
     return 100.0 * a / b;
   }
 
-  void print(bool tabbed_output) const {
+  void print(bool tabbed_output, bool stage1_only) const {
     if (tabbed_output) {
       char* filename_copy = reinterpret_cast<char*>(malloc(strlen(filename)+1));
       SIMDJSON_PUSH_DISABLE_WARNINGS
@@ -503,17 +503,21 @@ struct benchmarker {
           stats->blocks_with_16_structurals_flipped, percent(stats->blocks_with_16_structurals_flipped, stats->blocks));
       }
       printf("\n");
-      printf("All Stages (excluding allocation)\n");
-      print_aggregate("|    "   , all_stages_without_allocation.best);
-      // frequently, allocation is a tiny fraction of the running time so we omit it
-      if(allocate_stage.best.elapsed_sec() > 0.01 * all_stages_without_allocation.best.elapsed_sec()) {
-        printf("|- Allocation\n");
-        print_aggregate("|    ", allocate_stage.best);
+      if(!stage1_only) {
+        printf("All Stages (excluding allocation)\n");
+        print_aggregate("|    "   , all_stages_without_allocation.best);
+        // frequently, allocation is a tiny fraction of the running time so we omit it
+        if(allocate_stage.best.elapsed_sec() > 0.01 * all_stages_without_allocation.best.elapsed_sec()) {
+          printf("|- Allocation\n");
+          print_aggregate("|    ", allocate_stage.best);
+        }
       }
       printf("|- Stage 1\n");
       print_aggregate("|    ", stage1.best);
-      printf("|- Stage 2\n");
-      print_aggregate("|    ", stage2.best);
+      if(!stage1_only) {
+        printf("|- Stage 2\n");
+        print_aggregate("|    ", stage2.best);
+      }
       if (collector.has_events()) {
         double freq1 = (stage1.best.cycles() / stage1.best.elapsed_sec()) / 1000000000.0;
         double freq2 = (stage2.best.cycles() / stage2.best.elapsed_sec()) / 1000000000.0;

benchmark/distinct_user_id/boostjson.h

@@ -0,0 +1,29 @@
+#pragma once
+
+#ifdef SIMDJSON_COMPETITION_BOOSTJSON
+
+#include "distinct_user_id.h"
+
+namespace distinct_user_id {
+
+struct boostjson {
+  bool run(simdjson::padded_string &json, std::vector<uint64_t> &result) {
+
+    auto root = boost::json::parse(json);
+    for (const auto &tweet : root.at("statuses").as_array()) {
+      result.push_back(tweet.at("user").at("id").to_number<uint64_t>());
+
+      if (tweet.as_object().if_contains("retweeted_status")) {
+        result.push_back(tweet.at("retweeted_status").at("user").at("id").to_number<uint64_t>());
+      }
+    }
+
+    return true;
+  }
+};
+
+BENCHMARK_TEMPLATE(distinct_user_id, boostjson)->UseManualTime();
+
+} // namespace distinct_user_id
+
+#endif // SIMDJSON_COMPETITION_BOOSTJSON

benchmark/dom/parse.cpp

@@ -218,7 +218,7 @@ int main(int argc, char *argv[]) {
   if (!options.verbose) { progress.erase(); }
 
   for (size_t i=0; i<options.files.size(); i++) {
-    benchmarkers[i]->print(options.tabbed_output);
+    benchmarkers[i]->print(options.tabbed_output, options.stage1_only);
     delete benchmarkers[i];
   }
 

benchmark/event_counter.h

@@ -34,11 +34,15 @@
 #include <string>
 #include <vector>
 
-#include "linux-perf-events.h"
 #ifdef __linux__
+#include "linux-perf-events.h"
 #include <libgen.h>
 #endif
 
+#if __APPLE__ &&  __aarch64__
+#include "apple/apple_arm_events.h"
+#endif
+
 #include "simdjson.h"
 
 using std::string;
@@ -134,7 +138,7 @@ struct event_collector {
 
 #if defined(__linux__)
   LinuxEvents<PERF_TYPE_HARDWARE> linux_events;
-  event_collector(simdjson_unused bool quiet = false) : linux_events(vector<int>{
+  event_collector() : linux_events(vector<int>{
   #if SIMDJSON_SIMPLE_PERFORMANCE_COUNTERS
     PERF_COUNT_HW_CPU_CYCLES,
     PERF_COUNT_HW_INSTRUCTIONS,
@@ -149,8 +153,17 @@ struct event_collector {
   bool has_events() {
     return linux_events.is_working();
   }
+#elif __APPLE__ &&  __aarch64__
+  AppleEvents apple_events;
+  performance_counters diff;
+  event_collector() : diff(0) {
+    apple_events.setup_performance_counters();
+  }
+  bool has_events() {
+    return apple_events.setup_performance_counters();
+  }
 #else
-  event_collector(simdjson_unused bool _quiet = false) {}
+  event_collector() {}
   bool has_events() {
     return false;
   }
@@ -159,6 +172,8 @@ struct event_collector {
   simdjson_inline void start() {
 #if defined(__linux)
     linux_events.start();
+#elif __APPLE__ &&  __aarch64__
+    if(has_events()) { diff = apple_events.get_counters(); }
 #endif
     start_clock = steady_clock::now();
   }
@@ -166,6 +181,16 @@ struct event_collector {
     time_point<steady_clock> end_clock = steady_clock::now();
 #if defined(__linux)
     linux_events.end(count.event_counts);
+#elif __APPLE__ &&  __aarch64__
+    if(has_events()) {
+      performance_counters end = apple_events.get_counters();
+      diff = end - diff;
+    }
+    count.event_counts[0] = diff.cycles;
+    count.event_counts[1] = diff.instructions;
+    count.event_counts[2] = diff.missed_branches;
+    count.event_counts[3] = 0;
+    count.event_counts[4] = 0;
 #endif
     count.elapsed = end_clock - start_clock;
     return count;

benchmark/find_tweet/boostjson.h

@@ -0,0 +1,30 @@
+#pragma once
+
+#ifdef SIMDJSON_COMPETITION_BOOSTJSON
+
+#include "find_tweet.h"
+
+namespace find_tweet {
+
+struct boostjson {
+  using StringType=std::string;
+
+  bool run(simdjson::padded_string &json, uint64_t find_id, std::string &result) {
+
+    auto root = boost::json::parse(json);
+    for (const auto &tweet : root.at("statuses").as_array()) {
+      if (tweet.at("id") == find_id) {
+        result = tweet.at("text").as_string();
+        return true;
+      }
+    }
+
+    return false;
+  }
+};
+
+BENCHMARK_TEMPLATE(find_tweet, boostjson)->UseManualTime();
+
+} // namespace find_tweet
+
+#endif // SIMDJSON_COMPETITION_BOOSTJSON

benchmark/json2msgpack/boostjson.h

@@ -0,0 +1,104 @@
+#pragma once
+
+#ifdef SIMDJSON_COMPETITION_BOOSTJSON
+
+#include "json2msgpack.h"
+
+namespace json2msgpack {
+
+struct boostjson2msgpack {
+  inline std::string_view to_msgpack(const boost::json::value &root, uint8_t *buf) {
+    buff = buf;
+    recursive_processor(root);
+    return std::string_view(reinterpret_cast<char *>(buf), size_t(buff - buf));
+  }
+
+private:
+  uint8_t *buff{};
+
+  inline void write_double(const double d) noexcept {
+    *buff++ = 0xcb;
+    ::memcpy(buff, &d, sizeof(d));
+    buff += sizeof(d);
+  }
+
+  inline void write_byte(const uint8_t b) noexcept {
+    *buff = b;
+    buff++;
+  }
+
+  inline void write_uint32(const uint32_t w) noexcept {
+    ::memcpy(buff, &w, sizeof(w));
+    buff += sizeof(w);
+  }
+
+  inline void write_string(const std::string & str) {
+    write_byte(0xdb);
+    write_uint32(uint32_t(str.size()));
+    ::memcpy(buff, str.data(), str.size());
+    buff += str.size();
+  }
+
+  inline void recursive_processor(const boost::json::value &element) {
+    switch(element.kind()) {
+    case boost::json::kind::array: {
+      write_byte(0xdd);
+      const auto &array = element.as_array();
+      write_uint32(static_cast<uint32_t>(array.size()));
+      for (const auto &child : array) {
+        recursive_processor(child);
+      }
+    } break;
+
+    case boost::json::kind::object: {
+      write_byte(0xdf);
+      const auto &object = element.as_object();
+      write_uint32(static_cast<uint32_t>(object.size()));
+      for (const auto &child : object) {
+        write_string(child.key_c_str());
+        recursive_processor(child.value());
+      }
+    } break;
+
+    case boost::json::kind::int64:
+    case boost::json::kind::uint64:
+    case boost::json::kind::double_:
+      write_double(element.to_number<double>());
+      break;
+
+    case boost::json::kind::string:
+      write_string(element.as_string().c_str());
+      break;
+
+    case boost::json::kind::bool_:
+      write_byte(0xc2 + element.as_bool());
+      break;
+
+    case boost::json::kind::null:
+      write_byte(0xc0);
+      break;
+
+    default:
+      printf("unexpected\n");
+      break;
+    }
+  }
+};
+
+struct boostjson {
+  using StringType=std::string;
+
+  boostjson2msgpack parser{};
+
+  bool run(simdjson::padded_string &json, char *buffer, std::string_view &result) {
+    auto root = boost::json::parse(json);
+    result = parser.to_msgpack(root, reinterpret_cast<uint8_t *>(buffer));
+    return true;
+  }
+};
+
+BENCHMARK_TEMPLATE(json2msgpack, boostjson)->UseManualTime();
+
+} // namespace json2msgpack
+
+#endif // SIMDJSON_COMPETITION_BOOSTJSON

benchmark/json_benchmark/file_runner.h

@@ -24,7 +24,7 @@ struct file_runner : public runner_base<I> {
 
   simdjson_warn_unused bool before_run(benchmark::State &state) {
     if (!runner_base<I>::after_run(state)) { return false; };
-    // Copy the original json in case we did *in situ* last time
+    // Copy the original JSON in case we did *in situ* last time
     std::memcpy(json.data(), original_json.data(), original_json.size());
     return true;
   }

benchmark/json_benchmark/run_json_benchmark.h

@@ -19,7 +19,7 @@ void maybe_display_implementation() {
 template<typename B, typename R> static void run_json_benchmark(benchmark::State &state) {
   maybe_display_implementation();
 
-  event_collector collector(true);
+  event_collector collector;
   event_aggregate events;
 
   // Warmup and equality check (make sure the data is right!)

benchmark/json_benchmark/string_runner.h

@@ -13,7 +13,7 @@ struct string_runner : public runner_base<I> {
 
   simdjson_warn_unused bool before_run(benchmark::State &state) {
     if (!runner_base<I>::after_run(state)) { return false; };
-    // Copy the original json in case we did *in situ*
+    // Copy the original JSON in case we did *in situ*
     std::memcpy(json.data(), original_json.data(), original_json.size());
     return true;
   }

benchmark/kostya/boostjson.h

@@ -0,0 +1,29 @@
+#pragma once
+
+#ifdef SIMDJSON_COMPETITION_BOOSTJSON
+
+#include "kostya.h"
+
+namespace kostya {
+
+struct boostjson {
+  static constexpr diff_flags DiffFlags = diff_flags::IMPRECISE_FLOATS;
+
+  bool run(simdjson::padded_string &json, std::vector<point> &result) {
+    auto root = boost::json::parse(json);
+    for (const auto &point : root.at("coordinates").as_array()) {
+      result.emplace_back(json_benchmark::point{
+        point.at("x").to_number<double>(),
+        point.at("y").to_number<double>(),
+        point.at("z").to_number<double>()
+      });
+    }
+    return true;
+  }
+};
+
+BENCHMARK_TEMPLATE(kostya, boostjson)->UseManualTime();
+
+} // namespace kostya
+
+#endif // SIMDJSON_COMPETITION_BOOSTJSON

benchmark/large_random/boostjson.h

@@ -0,0 +1,29 @@
+#pragma once
+
+#ifdef SIMDJSON_COMPETITION_BOOSTJSON
+
+#include "large_random.h"
+
+namespace large_random {
+
+struct boostjson {
+  static constexpr diff_flags DiffFlags = diff_flags::IMPRECISE_FLOATS;
+
+  bool run(simdjson::padded_string &json, std::vector<point> &result) {
+    auto root = boost::json::parse(json);
+    for (const auto &point : root.as_array()) {
+      result.emplace_back(json_benchmark::point{
+        point.at("x").to_number<double>(),
+        point.at("y").to_number<double>(),
+        point.at("z").to_number<double>()
+      });
+    }
+    return true;
+  }
+};
+
+BENCHMARK_TEMPLATE(large_random, boostjson)->UseManualTime();
+
+} // namespace large_random
+
+#endif // SIMDJSON_COMPETITION_BOOSTJSON

benchmark/partial_tweets/boostjson.h

@@ -0,0 +1,43 @@
+#pragma once
+
+#ifdef SIMDJSON_COMPETITION_BOOSTJSON
+
+#include "partial_tweets.h"
+
+namespace partial_tweets {
+
+struct boostjson {
+  using StringType=std::string;
+
+  bool run(simdjson::padded_string &json, std::vector<tweet<StringType>> &result) {
+
+    auto root = boost::json::parse(json);
+    for (const auto &tweet : root.at("statuses").as_array()) {
+      const auto &user = tweet.at("user");
+
+      auto in_reply_to_status_id = tweet.as_object().if_contains("in_reply_to_status_id")
+        ? tweet.at("in_reply_to_status_id") : boost::json::value();
+
+      result.emplace_back(partial_tweets::tweet<StringType>{
+        tweet.at("created_at").as_string().c_str(),
+        tweet.at("id").to_number<uint64_t>(),
+        tweet.at("text").as_string().c_str(),
+        in_reply_to_status_id.is_null() ? 0 : in_reply_to_status_id.to_number<uint64_t>(),
+        {
+          user.at("id").to_number<uint64_t>(),
+          user.at("screen_name").as_string().c_str()
+        },
+        tweet.at("retweet_count").to_number<uint64_t>(),
+        tweet.at("favorite_count").to_number<uint64_t>()
+      });
+    }
+
+    return true;
+  }
+};
+
+BENCHMARK_TEMPLATE(partial_tweets, boostjson)->UseManualTime();
+
+} // namespace partial_tweets
+
+#endif // SIMDJSON_COMPETITION_BOOSTJSON

benchmark/top_tweet/boostjson.h

@@ -0,0 +1,37 @@
+#pragma once
+
+#if SIMDJSON_COMPETITION_BOOSTJSON
+
+#include "top_tweet.h"
+
+namespace top_tweet {
+
+using namespace simdjson;
+
+struct boostjson {
+  using StringType=std::string;
+
+  bool run(simdjson::padded_string &json, int64_t max_retweet_count, top_tweet_result<StringType> &result) {
+    result.retweet_count = -1;
+    boost::json::value top_tweet{};
+
+    auto root = boost::json::parse(json);
+    for (const auto &tweet : root.at("statuses").as_array()) {
+      int64_t retweet_count = tweet.at("retweet_count").as_int64();
+      if (retweet_count <= max_retweet_count && retweet_count >= result.retweet_count) {
+        result.retweet_count = retweet_count;
+        top_tweet = tweet;
+      }
+    }
+
+    result.text = top_tweet.at("text").as_string();
+    result.screen_name = top_tweet.at("user").at("screen_name").as_string();
+    return result.retweet_count != -1;
+  }
+};
+
+BENCHMARK_TEMPLATE(top_tweet, boostjson)->UseManualTime();
+
+} // namespace top_tweet
+
+#endif // SIMDJSON_COMPETITION_BOOSTJSON

cmake/developer-options.cmake

@@ -114,10 +114,14 @@ set(SIMDJSON_CXX_STANDARD 17 CACHE STRING "the C++ standard to use for simdjson"
 set(CMAKE_CXX_STANDARD ${SIMDJSON_CXX_STANDARD})
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
 set(CMAKE_CXX_EXTENSIONS OFF)
-set(CMAKE_MACOSX_RPATH OFF)
 set(CMAKE_THREAD_PREFER_PTHREAD ON)
 set(THREADS_PREFER_PTHREAD_FLAG ON)
+set(SIMDJSON_STRUCTURAL_INDEXER_STEP CACHE STRING "the SIMDJSON_STRUCTURAL_INDEXER_STEP variable")
 
+if(SIMDJSON_STRUCTURAL_INDEXER_STEP)
+  message(STATUS "Setting SIMDJSON_STRUCTURAL_INDEXER_STEP to ${SIMDJSON_STRUCTURAL_INDEXER_STEP}.")
+  add_compile_definitions(SIMDJSON_STRUCTURAL_INDEXER_STEP=${SIMDJSON_STRUCTURAL_INDEXER_STEP})
+endif()
 # LTO seems to create all sorts of fun problems. Let us
 # disable temporarily.
 #include(CheckIPOSupported)

cmake/simdjson-config.cmake.in

@@ -4,3 +4,4 @@ if("@SIMDJSON_ENABLE_THREADS@")
 endif()
 
 include("${CMAKE_CURRENT_LIST_DIR}/simdjsonTargets.cmake")
+include("${CMAKE_CURRENT_LIST_DIR}/simdjson_staticTargets.cmake" OPTIONAL)

dependencies/CMakeLists.txt

@@ -22,7 +22,7 @@ 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)
-
+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
 function(competition_scope_)
@@ -36,8 +36,8 @@ function(competition_scope_)
 #endif
 
 int main() {}
-]] USE_BOOST_JSON)
-  if(USE_BOOST_JSON)
+]] SIMDJSON_FOUND_STRING_VIEW)
+  if(SIMDJSON_FOUND_STRING_VIEW AND SIMDJSON_USE_BOOST_JSON)
     import_dependency(boostjson boostorg/json ee8d72d)
     add_library(boostjson STATIC "${boostjson_SOURCE_DIR}/src/src.cpp")
     target_compile_definitions(boostjson PUBLIC BOOST_JSON_STANDALONE)
@@ -104,7 +104,11 @@ int main() {}
   target_compile_definitions(rapidjson INTERFACE RAPIDJSON_HAS_STDSTRING)
   target_include_directories(rapidjson SYSTEM INTERFACE
           "${rapidjson_SOURCE_DIR}/include")
-  target_compile_definitions(rapidjson INTERFACE SIMDJSON_COMPETITION_RAPIDJSON)
+  if (CMAKE_COMPILER_IS_GNUCC AND CMAKE_CXX_COMPILER_VERSION VERSION_GREATER_EQUAL 14)
+    message(STATUS "Disabling rapidjson")
+  else()
+    target_compile_definitions(rapidjson INTERFACE SIMDJSON_COMPETITION_RAPIDJSON)
+  endif()
 
   import_dependency(sajson chadaustin/sajson 2dcfd35)
   add_library(sajson INTERFACE)
@@ -130,7 +134,7 @@ int main() {}
   add_library(competition-core INTERFACE)
   target_link_libraries(competition-core INTERFACE nlohmann_json rapidjson sajson cjson jsmn yyjson)
 
-  if(USE_BOOST_JSON)
+  if(TARGET boostjson)
      target_compile_definitions(boostjson INTERFACE HAS_BOOST_JSON)
      target_link_libraries(competition-core INTERFACE boostjson)
   endif()

doc/dom.md

@@ -223,13 +223,13 @@ dom::element cars = parser.parse(cars_json);
 cout << cars.at_pointer("/0/tire_pressure/1") << endl; // Prints 39.9
 ```
 
-A JSON Path is a sequence of segments each starting with the '/' character. Within arrays, an integer
+A JSON Pointer expression is a sequence of segments each starting with the '/' character. Within arrays, an integer
 index allows you to select the indexed node. Within objects, the string value of the key allows you to
 select the value. If your keys contain the characters '/' or '~', they must be escaped as '~1' and
-'~0' respectively. An empty JSON Path refers to the whole document.
+'~0' respectively. An empty JSON Pointer expression refers to the whole document.
 
 We also extend the JSON Pointer support to include *relative* paths.
-You can apply a JSON path to any node and the path gets interpreted relatively, as if the current node were a whole JSON document.
+You can apply a JSON Pointer expression to any node and the path gets interpreted relatively, as if the current node were a whole JSON document.
 
 Consider the following example:
 
@@ -329,10 +329,10 @@ int main(void) {
   simdjson::dom::parser parser;
   simdjson::dom::element tweets; // invalid until the get() succeeds
   auto error = parser.load("twitter.json").get(tweets);
-  if(error) { std::cerr << error << std::endl; return EXIT_FAILURE; }
+  if (error) { std::cerr << error << std::endl; return EXIT_FAILURE; }
   uint64_t identifier;
   error = tweets["statuses"].at(0)["id"].get(identifier);
-  if(error) { std::cerr << error << std::endl; return EXIT_FAILURE; }
+  if (error) { std::cerr << error << std::endl; return EXIT_FAILURE; }
   std::cout << identifier << std::endl;
   return EXIT_SUCCESS;
 }

doc/implementation-selection.md

@@ -11,22 +11,24 @@ CPU Architecture-Specific Implementations
 Overview
 --------
 
+
+
 The simdjson library takes advantage of SIMD instruction sets such as NEON, SSE and AVX to achieve
 much of its speed. Because these instruction sets work differently, simdjson has to compile a
 different version of the JSON parser for different CPU architectures, often with different
 algorithms to take better advantage of a given CPU!
 
 The current implementations are:
-* icelake: AVX-512F, AVX-512VBMI, etc.
-* haswell: AVX2 (2013 Intel Haswell or later)
+* icelake: AVX-512F, AVX-512_VBMI, AVX-512_VBMI2, AVX-512_DQ, AVX-512512_CD, AVX-512_BW, AVX-512_VL (2019 Intel Ice Lake, Intel Rocket Lake, Intel Sapphire Rapids, AMD Zen 4)
+* haswell: AVX2 (2013 Intel Haswell or later, all AMD Zen processors)
 * westmere: SSE4.2 (2010 Westmere or later).
 * arm64: 64-bit ARMv8-A NEON
-* ppc64: 64-bit POWER8 and POWER9 with VSX and ALTIVEC extensions. Both big endian and little endian are implemented, depends on the compiler you are using. The library is tested on recent, little-endian, POWER systems.
+* ppc64: 64-bit POWER8 and POWER9 with VSX and ALTIVEC extensions. Both big endian and little endian are implemented, depending on the compiler you are using. The library is tested on recent, little-endian, POWER systems.
 * fallback: A generic implementation that runs on any 64-bit processor.
 
 In many cases, you don't know where your compiled binary is going to run, so simdjson automatically
 compiles *all* the implementations into the executable. On Intel, it will include 4 implementations
-(icelake, haswell, westmere and fallback), on ARM it will include 2 (arm64 and fallback), and on PPC
+(icelake, haswell, westmere and fallback), on 64-bit ARM it will include just one since running dispatching is  unnecessary, and on PPC
 it will include 2 (ppc64 and fallback).
 
 If you know more about where you're going to run and want to save the space, you can disable any of
@@ -75,8 +77,7 @@ And look them up by name:
 ```c++
 cout << simdjson::get_available_implementations()["fallback"]->description() << endl;
 ```
-Though the fallback implementation should always be available, others might be missing. When
-an implementation is not available, the bracket call `simdjson::get_available_implementations()[name]`
+When an implementation is not available, the bracket call `simdjson::get_available_implementations()[name]`
 will return the null pointer.
 
 The available implementations have been compiled but may not necessarily be run safely on your system
@@ -101,8 +102,8 @@ by comparing it with the null pointer.
 
 ```c++
 auto my_implementation = simdjson::get_available_implementations()["haswell"];
-if(! my_implementation) { exit(1); }
-if(! my_implementation->supported_by_runtime_system()) { exit(1); }
+if (! my_implementation) { exit(1); }
+if (! my_implementation->supported_by_runtime_system()) { exit(1); }
 simdjson::get_active_implementation() = my_implementation;
 ```
 
@@ -113,7 +114,7 @@ You should call `supported_by_runtime_system()` to compare the processor's featu
 
 ```c++
 for (auto implementation : simdjson::get_available_implementations()) {
-  if(implementation->supported_by_runtime_system()) {
+  if (implementation->supported_by_runtime_system()) {
     cout << implementation->name() << ": " << implementation->description() << endl;
   }
 }

doc/iterate_many.md

@@ -17,6 +17,9 @@ Contents
 
 - [Motivations](#motivations)
 - [How it works](#how-it-works)
+  - [Context](#context)
+  - [Design](#design)
+  - [Threads](#threads)
 - [Support](#support)
 - [API](#api)
 - [Use cases](#use-cases)
@@ -193,12 +196,12 @@ Let us illustrate the idea with code:
     simdjson::ondemand::parser parser;
     simdjson::ondemand::document_stream stream;
     auto error = parser.iterate_many(json).get(stream);
-    if( error ) { /* do something */ }
+    if (error) { /* do something */ }
     auto i = stream.begin();
 	 size_t count{0};
     for(; i != stream.end(); ++i) {
         auto doc = *i;
-        if(!i.error()) {
+        if (!i.error()) {
           std::cout << "got full document at " << i.current_index() << std::endl;
           std::cout << i.source() << std::endl;
           count++;
@@ -234,7 +237,7 @@ Consider the following example where a truncated document (`{"key":"intentionall
     simdjson::ondemand::parser parser;
     simdjson::ondemand::document_stream stream;
     auto error = parser.iterate_many(json,json.size()).get(stream);
-    if(error) { std::cerr << error << std::endl; return; }
+    if (error) { std::cerr << error << std::endl; return; }
     for(auto i = stream.begin(); i != stream.end(); ++i) {
        std::cout << i.source() << std::endl;
     }
@@ -266,7 +269,7 @@ Example:
     // we pass 'true' to the allow_comma parameter, the batch size will be set to at least
     // the document size.
     auto error = parser.iterate_many(json, 32, true).get(doc_stream);
-    if(error) { std::cerr << error << std::endl; return; }
+    if (error) { std::cerr << error << std::endl; return; }
     for (auto doc : doc_stream) {
         std::cout << doc.type() << std::endl;
     }

doc/ondemand_design.md

@@ -679,14 +679,14 @@ in production systems:
     ondemand::object c1 = parent["child1"];
     // c1 owns the focus
     //
-    if(std::string_view(c1["name"]) != "John") { ... }
+    if (std::string_view(c1["name"]) != "John") { ... }
     // c2 attempts to grab the focus from parent but fails
     ondemand::object c2 = parent["child2"];
     // c2 is now in an unsafe state and the following line would be unsafe
-    // if(std::string_view(c2["name"]) != "Daniel") { return false; }
+    // if (std::string_view(c2["name"]) != "Daniel") { return false; }
 ```
 
-    A correct usage is given by the following example:
+A correct usage is given by the following example:
 
 ```C++
     ondemand::parser parser;
@@ -697,7 +697,7 @@ in production systems:
     {
       ondemand::object c1 = parent["child1"];
       // c1 grabbed the focus from parent
-      if(std::string_view(c1["name"]) != "John") { return false; }
+      if (std::string_view(c1["name"]) != "John") { return false; }
     }
     // c1 went out of scope, so its destructor was called and the focus
     // was handed back to parent.
@@ -705,7 +705,7 @@ in production systems:
       ondemand::object c2 = parent["child2"];
       // c2 grabbed the focus from parent
       // the following is safe:
-      if(std::string_view(c2["name"]) != "Daniel") { return false; }
+      if (std::string_view(c2["name"]) != "Daniel") { return false; }
     }
 ```
 
@@ -779,4 +779,4 @@ Instead of specifying a specific microarchitecture, you can let your compiler do
 
 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 useful for best performance on x64 (e.g., Intel) systems but it is generally unsupported on some platforms such as ARM (aarch64) or POWER.
+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

@@ -184,12 +184,12 @@ Let us illustrate the idea with code:
     simdjson::dom::parser parser;
     simdjson::dom::document_stream stream;
     auto error = parser.parse_many(json).get(stream);
-    if( error ) { /* do something */ }
+    if (error) { /* do something */ }
     auto i = stream.begin();
     size_t count{0};
     for(; i != stream.end(); ++i) {
         auto doc = *i;
-        if(!doc.error()) {
+        if (!doc.error()) {
           std::cout << "got full document at " << i.current_index() << std::endl;
           std::cout << i.source() << std::endl;
           count++;
@@ -225,7 +225,7 @@ Consider the following example where a truncated document (`{"key":"intentionall
     simdjson::dom::parser parser;
     simdjson::dom::document_stream stream;
     auto error = parser.parse_many(json,json.size()).get(stream);
-    if(error) { std::cerr << error << std::endl; return; }
+    if (error) { std::cerr << error << std::endl; return; }
     for(auto doc : stream) {
        std::cout << doc << std::endl;
     }

doc/performance.md

@@ -159,7 +159,7 @@ When compiling with Visual Studio, we recommend the flags `/Ob2 /O2` or better.
 
 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).
 
-Under Windows, we also support the GNU GCC compiler via MSYS2. The performance of 64-bit MSYS2 under Windows excellent (on par with Linux).
+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).
 
 
 Power Usage and Downclocking

doc/tape.md

@@ -29,7 +29,7 @@ It is sometimes useful to start with an example. Consider the following JSON doc
 The following is a dump of the content of the tape, with the first number of each line representing the index of a tape element.
 
 ### The Tape
-| index | element (64 bit word)                                               |
+| index | element (64-bit word)                                               |
 | ----- | ------------------------------------------------------------------- |
 | 0     | r	// pointing to 39 (right after last node)                         |
 | 1     | {	// pointing to next tape location 38 (first node after the scope) |

fuzz/build_fuzzer_variants.sh

@@ -78,7 +78,7 @@ fi
 # Different levels may uncover different types of bugs, see this interesting
 # thread: https://github.com/google/oss-fuzz/issues/2295#issuecomment-481493392
 # Oss-fuzz uses -O1 so it may be relevant to use something else than that,
-# to do something oss-fuzz doesn't.
+# to do something oss-fuzz does not do.
 variant=sanitizers-O3
 
     if [ ! -d build-$variant ] ; then

fuzz/fuzz_atpointer.cpp

@@ -7,11 +7,11 @@
 
 extern "C" int LLVMFuzzerTestOneInput(const uint8_t *Data, size_t Size) {
 
-  // Split data into two strings, json pointer and the document string.
+  // Split data into two strings, JSON Pointer and the document string.
   // Might end up with none, either or both being empty, important for
   // covering edge cases such as
   // https://github.com/simdjson/simdjson/issues/1142 Inputs missing the
-  // separator line will get an empty json pointer but the all the input put in
+  // separator line will get an empty JSON Pointer but the all the input put in
   // the document string. This means test data from other fuzzers that take json
   // input works for this fuzzer as well.
   FuzzData fd(Data, Size);

include/simdjson/arm64/base.h

@@ -1,9 +1,9 @@
 #ifndef SIMDJSON_ARM64_BASE_H
 #define SIMDJSON_ARM64_BASE_H
 
-#ifndef SIMDJSON_AMALGAMATED
+#ifndef SIMDJSON_CONDITIONAL_INCLUDE
 #include "simdjson/base.h"
-#endif // SIMDJSON_AMALGAMATED
+#endif // SIMDJSON_CONDITIONAL_INCLUDE
 
 namespace simdjson {
 /**
@@ -23,11 +23,4 @@ template <typename T> struct simd8x64;
 } // namespace arm64
 } // namespace simdjson
 
-#ifndef SIMDJSON_AMALGAMATED
-// If we're editing one of the files in this directory, begin the implementation!
-#ifndef SIMDJSON_IMPLEMENTATION
-#include "simdjson/arm64/begin.h"
-#endif
-#endif // SIMDJSON_AMALGAMATED
-
 #endif // SIMDJSON_ARM64_BASE_H

include/simdjson/arm64/begin.h

@@ -6,3 +6,5 @@
 #include "simdjson/arm64/numberparsing_defs.h"
 #include "simdjson/arm64/simd.h"
 #include "simdjson/arm64/stringparsing_defs.h"
+
+#define SIMDJSON_SKIP_BACKSLASH_SHORT_CIRCUIT 1

include/simdjson/arm64/bitmanipulation.h

@@ -1,11 +1,13 @@
 #ifndef SIMDJSON_ARM64_BITMANIPULATION_H
 #define SIMDJSON_ARM64_BITMANIPULATION_H
 
+#ifndef SIMDJSON_CONDITIONAL_INCLUDE
 #include "simdjson/arm64/base.h"
 #include "simdjson/arm64/intrinsics.h"
+#endif // SIMDJSON_CONDITIONAL_INCLUDE
 
 namespace simdjson {
-namespace SIMDJSON_IMPLEMENTATION {
+namespace arm64 {
 namespace {
 
 // We sometimes call trailing_zero on inputs that are zero,
@@ -98,7 +100,7 @@ simdjson_inline bool add_overflow(uint64_t value1, uint64_t value2, uint64_t *re
 }
 
 } // unnamed namespace
-} // namespace SIMDJSON_IMPLEMENTATION
+} // namespace arm64
 } // namespace simdjson
 
 #endif // SIMDJSON_ARM64_BITMANIPULATION_H

include/simdjson/arm64/bitmask.h

@@ -1,10 +1,12 @@
 #ifndef SIMDJSON_ARM64_BITMASK_H
 #define SIMDJSON_ARM64_BITMASK_H
 
+#ifndef SIMDJSON_CONDITIONAL_INCLUDE
 #include "simdjson/arm64/base.h"
+#endif // SIMDJSON_CONDITIONAL_INCLUDE
 
 namespace simdjson {
-namespace SIMDJSON_IMPLEMENTATION {
+namespace arm64 {
 namespace {
 
 //

include/simdjson/arm64/end.h

@@ -1 +1,6 @@
+#ifndef SIMDJSON_CONDITIONAL_INCLUDE
+#include "simdjson/arm64/base.h"
+#endif // SIMDJSON_CONDITIONAL_INCLUDE
+
+#undef SIMDJSON_SKIP_BACKSLASH_SHORT_CIRCUIT
 #undef SIMDJSON_IMPLEMENTATION

include/simdjson/arm64/implementation.h

@@ -1,10 +1,11 @@
 #ifndef SIMDJSON_ARM64_IMPLEMENTATION_H
 #define SIMDJSON_ARM64_IMPLEMENTATION_H
 
-#ifndef SIMDJSON_AMALGAMATED
+#ifndef SIMDJSON_CONDITIONAL_INCLUDE
+#include "simdjson/base.h"
 #include "simdjson/implementation.h"
 #include "simdjson/internal/instruction_set.h"
-#endif // SIMDJSON_AMALGAMATED
+#endif // SIMDJSON_CONDITIONAL_INCLUDE
 
 namespace simdjson {
 namespace arm64 {

include/simdjson/arm64/intrinsics.h

@@ -1,12 +1,14 @@
 #ifndef SIMDJSON_ARM64_INTRINSICS_H
 #define SIMDJSON_ARM64_INTRINSICS_H
 
+#ifndef SIMDJSON_CONDITIONAL_INCLUDE
+#include "simdjson/arm64/base.h"
+#endif // SIMDJSON_CONDITIONAL_INCLUDE
+
 // This should be the correct header whether
 // you use visual studio or other compilers.
 #include <arm_neon.h>
 
-#include "simdjson/arm64/base.h"
-
 static_assert(sizeof(uint8x16_t) <= simdjson::SIMDJSON_PADDING, "insufficient padding for arm64");
 
 #endif //  SIMDJSON_ARM64_INTRINSICS_H

include/simdjson/arm64/numberparsing_defs.h

@@ -1,22 +1,21 @@
 #ifndef SIMDJSON_ARM64_NUMBERPARSING_DEFS_H
 #define SIMDJSON_ARM64_NUMBERPARSING_DEFS_H
 
+#ifndef SIMDJSON_CONDITIONAL_INCLUDE
 #include "simdjson/arm64/base.h"
 #include "simdjson/arm64/intrinsics.h"
+#include "simdjson/internal/numberparsing_tables.h"
+#endif // SIMDJSON_CONDITIONAL_INCLUDE
+
+#include <cstring>
 
 #if _M_ARM64
 // __umulh requires intrin.h
 #include <intrin.h>
 #endif // _M_ARM64
 
-#include <cstring>
-
-#ifndef SIMDJSON_AMALGAMATED
-#include "simdjson/internal/numberparsing_tables.h"
-#endif // SIMDJSON_AMALGAMATED
-
 namespace simdjson {
-namespace SIMDJSON_IMPLEMENTATION {
+namespace arm64 {
 namespace numberparsing {
 
 // we don't have SSE, so let us use a scalar function
@@ -49,7 +48,7 @@ simdjson_inline internal::value128 full_multiplication(uint64_t value1, uint64_t
 }
 
 } // namespace numberparsing
-} // namespace SIMDJSON_IMPLEMENTATION
+} // namespace arm64
 } // namespace simdjson
 
 #define SIMDJSON_SWAR_NUMBER_PARSING 1

include/simdjson/arm64/simd.h

@@ -1,15 +1,14 @@
 #ifndef SIMDJSON_ARM64_SIMD_H
 #define SIMDJSON_ARM64_SIMD_H
 
+#ifndef SIMDJSON_CONDITIONAL_INCLUDE
 #include "simdjson/arm64/base.h"
 #include "simdjson/arm64/bitmanipulation.h"
-
-#ifndef SIMDJSON_AMALGAMATED
 #include "simdjson/internal/simdprune_tables.h"
-#endif // SIMDJSON_AMALGAMATED
+#endif // SIMDJSON_CONDITIONAL_INCLUDE
 
 namespace simdjson {
-namespace SIMDJSON_IMPLEMENTATION {
+namespace arm64 {
 namespace {
 namespace simd {
 
@@ -18,89 +17,53 @@ namespace {
 // Start of private section with Visual Studio workaround
 
 
-/**
- * make_uint8x16_t initializes a SIMD register (uint8x16_t).
- * This is needed because, incredibly, the syntax uint8x16_t x = {1,2,3...}
- * is not recognized under Visual Studio! This is a workaround.
- * Using a std::initializer_list<uint8_t>  as a parameter resulted in
- * inefficient code. With the current approach, if the parameters are
- * compile-time constants,
- * GNU GCC compiles it to ldr, the same as uint8x16_t x = {1,2,3...}.
- * You should not use this function except for compile-time constants:
- * it is not efficient.
- */
-simdjson_inline uint8x16_t make_uint8x16_t(uint8_t x1,  uint8_t x2,  uint8_t x3,  uint8_t x4,
-                                         uint8_t x5,  uint8_t x6,  uint8_t x7,  uint8_t x8,
-                                         uint8_t x9,  uint8_t x10, uint8_t x11, uint8_t x12,
-                                         uint8_t x13, uint8_t x14, uint8_t x15, uint8_t x16) {
-  // Doing a load like so end ups generating worse code.
-  // uint8_t array[16] = {x1, x2, x3, x4, x5, x6, x7, x8,
-  //                     x9, x10,x11,x12,x13,x14,x15,x16};
-  // return vld1q_u8(array);
-  uint8x16_t x{};
-  // incredibly, Visual Studio does not allow x[0] = x1
-  x = vsetq_lane_u8(x1, x, 0);
-  x = vsetq_lane_u8(x2, x, 1);
-  x = vsetq_lane_u8(x3, x, 2);
-  x = vsetq_lane_u8(x4, x, 3);
-  x = vsetq_lane_u8(x5, x, 4);
-  x = vsetq_lane_u8(x6, x, 5);
-  x = vsetq_lane_u8(x7, x, 6);
-  x = vsetq_lane_u8(x8, x, 7);
-  x = vsetq_lane_u8(x9, x, 8);
-  x = vsetq_lane_u8(x10, x, 9);
-  x = vsetq_lane_u8(x11, x, 10);
-  x = vsetq_lane_u8(x12, x, 11);
-  x = vsetq_lane_u8(x13, x, 12);
-  x = vsetq_lane_u8(x14, x, 13);
-  x = vsetq_lane_u8(x15, x, 14);
-  x = vsetq_lane_u8(x16, x, 15);
-  return x;
-}
+#ifndef simdjson_make_uint8x16_t
+#define simdjson_make_uint8x16_t(x1, x2, x3, x4, x5, x6, x7, x8, x9, x10, x11, x12, \
+                             x13, x14, x15, x16)                                   \
+   ([=]() {                                                                        \
+     uint8_t array[16] = {x1, x2,  x3,  x4,  x5,  x6,  x7,  x8,                    \
+                                 x9, x10, x11, x12, x13, x14, x15, x16};           \
+     return vld1q_u8(array);                                                       \
+   }())
+#endif
+#ifndef simdjson_make_int8x16_t
+#define simdjson_make_int8x16_t(x1, x2, x3, x4, x5, x6, x7, x8, x9, x10, x11, x12, \
+                             x13, x14, x15, x16)                                  \
+   ([=]() {                                                                       \
+     int8_t array[16] = {x1, x2,  x3,  x4,  x5,  x6,  x7,  x8,                    \
+                                 x9, x10, x11, x12, x13, x14, x15, x16};          \
+     return vld1q_s8(array);                                                      \
+   }())
+#endif
 
-simdjson_inline uint8x8_t make_uint8x8_t(uint8_t x1,  uint8_t x2,  uint8_t x3,  uint8_t x4,
-                                         uint8_t x5,  uint8_t x6,  uint8_t x7,  uint8_t x8) {
-  uint8x8_t x{};
-  x = vset_lane_u8(x1, x, 0);
-  x = vset_lane_u8(x2, x, 1);
-  x = vset_lane_u8(x3, x, 2);
-  x = vset_lane_u8(x4, x, 3);
-  x = vset_lane_u8(x5, x, 4);
-  x = vset_lane_u8(x6, x, 5);
-  x = vset_lane_u8(x7, x, 6);
-  x = vset_lane_u8(x8, x, 7);
-  return x;
-}
-
-// We have to do the same work for make_int8x16_t
-simdjson_inline int8x16_t make_int8x16_t(int8_t x1,  int8_t x2,  int8_t x3,  int8_t x4,
-                                       int8_t x5,  int8_t x6,  int8_t x7,  int8_t x8,
-                                       int8_t x9,  int8_t x10, int8_t x11, int8_t x12,
-                                       int8_t x13, int8_t x14, int8_t x15, int8_t x16) {
-  // Doing a load like so end ups generating worse code.
-  // int8_t array[16] = {x1, x2, x3, x4, x5, x6, x7, x8,
-  //                     x9, x10,x11,x12,x13,x14,x15,x16};
-  // return vld1q_s8(array);
-  int8x16_t x{};
-  // incredibly, Visual Studio does not allow x[0] = x1
-  x = vsetq_lane_s8(x1, x, 0);
-  x = vsetq_lane_s8(x2, x, 1);
-  x = vsetq_lane_s8(x3, x, 2);
-  x = vsetq_lane_s8(x4, x, 3);
-  x = vsetq_lane_s8(x5, x, 4);
-  x = vsetq_lane_s8(x6, x, 5);
-  x = vsetq_lane_s8(x7, x, 6);
-  x = vsetq_lane_s8(x8, x, 7);
-  x = vsetq_lane_s8(x9, x, 8);
-  x = vsetq_lane_s8(x10, x, 9);
-  x = vsetq_lane_s8(x11, x, 10);
-  x = vsetq_lane_s8(x12, x, 11);
-  x = vsetq_lane_s8(x13, x, 12);
-  x = vsetq_lane_s8(x14, x, 13);
-  x = vsetq_lane_s8(x15, x, 14);
-  x = vsetq_lane_s8(x16, x, 15);
-  return x;
-}
+#ifndef simdjson_make_uint8x8_t
+#define simdjson_make_uint8x8_t(x1, x2, x3, x4, x5, x6, x7, x8)                \
+   ([=]() {                                                                    \
+     uint8_t array[8] = {x1, x2,  x3,  x4,  x5,  x6,  x7,  x8};                \
+     return vld1_u8(array);                                                    \
+   }())
+#endif
+#ifndef simdjson_make_int8x8_t
+#define simdjson_make_int8x8_t(x1, x2, x3, x4, x5, x6, x7, x8)                 \
+   ([=]() {                                                                    \
+     int8_t array[8] = {x1, x2,  x3,  x4,  x5,  x6,  x7,  x8};                 \
+     return vld1_s8(array);                                                    \
+   }())
+#endif
+#ifndef simdjson_make_uint16x8_t
+#define simdjson_make_uint16x8_t(x1, x2, x3, x4, x5, x6, x7, x8)               \
+   ([=]() {                                                                    \
+     uint16_t array[8] = {x1, x2,  x3,  x4,  x5,  x6,  x7,  x8};               \
+     return vld1q_u16(array);                                                  \
+   }())
+#endif
+#ifndef simdjson_make_int16x8_t
+#define simdjson_make_int16x8_t(x1, x2, x3, x4, x5, x6, x7, x8)                \
+   ([=]() {                                                                    \
+     int16_t array[8] = {x1, x2,  x3,  x4,  x5,  x6,  x7,  x8};                \
+     return vld1q_s16(array);                                                  \
+   }())
+#endif
 
 // End of private section with Visual Studio workaround
 } // namespace
@@ -159,7 +122,7 @@ simdjson_inline int8x16_t make_int8x16_t(int8_t x1,  int8_t x2,  int8_t x3,  int
     // purposes (cutting it down to uint16_t costs performance in some compilers).
     simdjson_inline uint32_t to_bitmask() const {
 #ifdef SIMDJSON_REGULAR_VISUAL_STUDIO
-      const uint8x16_t bit_mask =  make_uint8x16_t(0x01, 0x02, 0x4, 0x8, 0x10, 0x20, 0x40, 0x80,
+      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
       const uint8x16_t bit_mask =  {0x01, 0x02, 0x4, 0x8, 0x10, 0x20, 0x40, 0x80,
@@ -193,7 +156,7 @@ simdjson_inline int8x16_t make_int8x16_t(int8_t x1,  int8_t x2,  int8_t x3,  int
     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
-    ) : simd8(make_uint8x16_t(
+    ) : simd8(simdjson_make_uint8x16_t(
       v0, v1, v2, v3, v4, v5, v6, v7,
       v8, v9, v10,v11,v12,v13,v14,v15
     )) {}
@@ -284,7 +247,7 @@ simdjson_inline int8x16_t make_int8x16_t(int8_t x1,  int8_t x2,  int8_t x3,  int
       uint8x16_t shufmask = vreinterpretq_u8_u64(shufmask64);
       // we increment by 0x08 the second half of the mask
 #ifdef SIMDJSON_REGULAR_VISUAL_STUDIO
-      uint8x16_t inc = make_uint8x16_t(0, 0, 0, 0, 0, 0, 0, 0, 0x08, 0x08, 0x08, 0x08, 0x08, 0x08, 0x08, 0x08);
+      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};
 #endif
@@ -314,7 +277,7 @@ simdjson_inline int8x16_t make_int8x16_t(int8_t x1,  int8_t x2,  int8_t x3,  int
       uint8x8_t compactmask2 = vcreate_u8(thintable_epi8[mask2]);
       // we increment by 0x08 the second half of the mask
 #ifdef SIMDJSON_REGULAR_VISUAL_STUDIO
-      uint8x8_t inc = make_uint8x8_t(0x08, 0x08, 0x08, 0x08, 0x08, 0x08, 0x08, 0x08);
+      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};
 #endif
@@ -369,7 +332,7 @@ simdjson_inline int8x16_t make_int8x16_t(int8_t x1,  int8_t x2,  int8_t x3,  int
     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
-    ) : simd8(make_int8x16_t(
+    ) : simd8(simdjson_make_int8x16_t(
       v0, v1, v2, v3, v4, v5, v6, v7,
       v8, v9, v10,v11,v12,v13,v14,v15
     )) {}
@@ -487,7 +450,7 @@ simdjson_inline int8x16_t make_int8x16_t(int8_t x1,  int8_t x2,  int8_t x3,  int
 
     simdjson_inline uint64_t to_bitmask() const {
 #ifdef SIMDJSON_REGULAR_VISUAL_STUDIO
-      const uint8x16_t bit_mask = make_uint8x16_t(
+      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
       );
@@ -528,7 +491,7 @@ simdjson_inline int8x16_t make_int8x16_t(int8_t x1,  int8_t x2,  int8_t x3,  int
 
 } // namespace simd
 } // unnamed namespace
-} // namespace SIMDJSON_IMPLEMENTATION
+} // namespace arm64
 } // namespace simdjson
 
 #endif // SIMDJSON_ARM64_SIMD_H

include/simdjson/arm64/stringparsing_defs.h

@@ -1,12 +1,14 @@
 #ifndef SIMDJSON_ARM64_STRINGPARSING_DEFS_H
 #define SIMDJSON_ARM64_STRINGPARSING_DEFS_H
 
+#ifndef SIMDJSON_CONDITIONAL_INCLUDE
 #include "simdjson/arm64/base.h"
 #include "simdjson/arm64/simd.h"
 #include "simdjson/arm64/bitmanipulation.h"
+#endif // SIMDJSON_CONDITIONAL_INCLUDE
 
 namespace simdjson {
-namespace SIMDJSON_IMPLEMENTATION {
+namespace arm64 {
 namespace {
 
 using namespace simd;
@@ -45,7 +47,7 @@ simdjson_inline backslash_and_quote backslash_and_quote::copy_and_find(const uin
 }
 
 } // unnamed namespace
-} // namespace SIMDJSON_IMPLEMENTATION
+} // namespace arm64
 } // namespace simdjson
 
 #endif // SIMDJSON_ARM64_STRINGPARSING_DEFS_H

include/simdjson/builtin.h

@@ -6,7 +6,7 @@
 
 #include "simdjson/generic/dependencies.h"
 
-#define SIMDJSON_AMALGAMATED
+#define SIMDJSON_CONDITIONAL_INCLUDE
 
 #if SIMDJSON_BUILTIN_IMPLEMENTATION_IS(arm64)
 #include "simdjson/arm64.h"
@@ -24,6 +24,6 @@
 #error Unknown SIMDJSON_BUILTIN_IMPLEMENTATION
 #endif
 
-#undef SIMDJSON_AMALGAMATED
+#undef SIMDJSON_CONDITIONAL_INCLUDE
 
 #endif // SIMDJSON_BUILTIN_H

include/simdjson/builtin/implementation.h

@@ -5,7 +5,7 @@
 
 #include "simdjson/generic/dependencies.h"
 
-#define SIMDJSON_AMALGAMATED
+#define SIMDJSON_CONDITIONAL_INCLUDE
 
 #if SIMDJSON_BUILTIN_IMPLEMENTATION_IS(arm64)
 #include "simdjson/arm64/implementation.h"
@@ -23,7 +23,7 @@
 #error Unknown SIMDJSON_BUILTIN_IMPLEMENTATION
 #endif
 
-#undef SIMDJSON_AMALGAMATED
+#undef SIMDJSON_CONDITIONAL_INCLUDE
 
 namespace simdjson {
   /**

include/simdjson/builtin/ondemand.h

@@ -6,7 +6,7 @@
 
 #include "simdjson/generic/ondemand/dependencies.h"
 
-#define SIMDJSON_AMALGAMATED
+#define SIMDJSON_CONDITIONAL_INCLUDE
 
 #if SIMDJSON_BUILTIN_IMPLEMENTATION_IS(arm64)
 #include "simdjson/arm64/ondemand.h"
@@ -24,7 +24,7 @@
 #error Unknown SIMDJSON_BUILTIN_IMPLEMENTATION
 #endif
 
-#undef SIMDJSON_AMALGAMATED
+#undef SIMDJSON_CONDITIONAL_INCLUDE
 
 namespace simdjson {
   /**

include/simdjson/compiler_check.h

@@ -32,4 +32,12 @@
 #error simdjson requires a compiler compliant with the C++11 standard
 #endif
 
+#ifndef SIMDJSON_IF_CONSTEXPR
+#if SIMDJSON_CPLUSPLUS17
+#define SIMDJSON_IF_CONSTEXPR if constexpr
+#else
+#define SIMDJSON_IF_CONSTEXPR if
+#endif
+#endif
+
 #endif // SIMDJSON_COMPILER_CHECK_H

include/simdjson/dom.h

@@ -10,18 +10,12 @@
 #include "simdjson/dom/parser.h"
 #include "simdjson/dom/serialization.h"
 
-// Deprecated API
-#include "simdjson/dom/jsonparser.h"
-#include "simdjson/dom/parsedjson.h"
-#include "simdjson/dom/parsedjson_iterator.h"
-
 // Inline functions
 #include "simdjson/dom/array-inl.h"
 #include "simdjson/dom/document_stream-inl.h"
 #include "simdjson/dom/document-inl.h"
 #include "simdjson/dom/element-inl.h"
 #include "simdjson/dom/object-inl.h"
-#include "simdjson/dom/parsedjson_iterator-inl.h"
 #include "simdjson/dom/parser-inl.h"
 #include "simdjson/internal/tape_ref-inl.h"
 #include "simdjson/dom/serialization-inl.h"

include/simdjson/dom/array.h

@@ -19,11 +19,14 @@ public:
   public:
     using value_type = element;
     using difference_type = std::ptrdiff_t;
+    using pointer = void;
+    using reference = value_type;
+    using iterator_category = std::forward_iterator_tag;
 
     /**
      * Get the actual value
      */
-    inline value_type operator*() const noexcept;
+    inline reference operator*() const noexcept;
     /**
      * Get the next value.
      *

include/simdjson/dom/document-inl.h

@@ -5,10 +5,12 @@
 
 #include "simdjson/dom/base.h"
 #include "simdjson/dom/document.h"
-#include "simdjson/dom/element.h"
+#include "simdjson/dom/element-inl.h"
 #include "simdjson/internal/tape_ref-inl.h"
 #include "simdjson/internal/jsonformatutils.h"
 
+#include <cstring>
+
 namespace simdjson {
 namespace dom {
 

include/simdjson/dom/document_stream.h

@@ -224,8 +224,7 @@ private:
    * Parse the next document found in the buffer previously given to document_stream.
    *
    * The content should be a valid JSON document encoded as UTF-8. If there is a
-   * UTF-8 BOM, the caller is responsible for omitting it, UTF-8 BOM are
-   * discouraged.
+   * UTF-8 BOM, the parser skips it.
    *
    * You do NOT need to pre-allocate a parser.  This function takes care of
    * pre-allocating a capacity defined by the batch_size defined when creating the

include/simdjson/dom/element-inl.h

@@ -7,8 +7,12 @@
 #include "simdjson/dom/object.h"
 #include "simdjson/internal/tape_type.h"
 
+#include "simdjson/dom/object-inl.h"
+#include "simdjson/error-inl.h"
+
 #include <ostream>
 #include <limits>
+
 namespace simdjson {
 
 //
@@ -406,6 +410,12 @@ inline simdjson_result<element> element::at_key(std::string_view key) const noex
 inline simdjson_result<element> element::at_key_case_insensitive(std::string_view key) const noexcept {
   return get<object>().at_key_case_insensitive(key);
 }
+inline bool element::operator<(const element &other) const noexcept {
+  return tape.json_index < other.tape.json_index;
+}
+inline bool element::operator==(const element &other) const noexcept {
+  return tape.json_index == other.tape.json_index;
+}
 
 inline bool element::dump_raw_tape(std::ostream &out) const noexcept {
   SIMDJSON_DEVELOPMENT_ASSERT(tape.usable()); // https://github.com/simdjson/simdjson/issues/1914

include/simdjson/dom/element.h

@@ -211,7 +211,11 @@ public:
   inline simdjson_result<T> get() const noexcept {
     // Unless the simdjson library provides an inline implementation, calling this method should
     // immediately fail.
-    static_assert(!sizeof(T), "The get method with given type is not implemented by the simdjson library.");
+    static_assert(!sizeof(T), "The get method with given type is not implemented by the simdjson library. "
+      "The supported types are Boolean (bool), numbers (double, uint64_t, int64_t), "
+      "strings (std::string_view, const char *), arrays (dom::array) and objects (dom::object). "
+      "We recommend you use get_double(), get_bool(), get_uint64(), get_int64(), "
+      "get_object(), get_array() or get_string() instead of the get template.");
   }
 
   /**
@@ -289,7 +293,7 @@ public:
    *
    * @return The integer value.
    * @exception simdjson_error(INCORRECT_TYPE) if the JSON element is not an integer
-   * @exception simdjson_error(NUMBER_OUT_OF_RANGE) if the integer doesn't fit in 64 bits or is negative
+   * @exception simdjson_error(NUMBER_OUT_OF_RANGE) if the integer does not fit in 64 bits or is negative
    */
   inline operator uint64_t() const noexcept(false);
   /**
@@ -297,7 +301,7 @@ public:
    *
    * @return The integer value.
    * @exception simdjson_error(INCORRECT_TYPE) if the JSON element is not an integer
-   * @exception simdjson_error(NUMBER_OUT_OF_RANGE) if the integer doesn't fit in 64 bits
+   * @exception simdjson_error(NUMBER_OUT_OF_RANGE) if the integer does not fit in 64 bits
    */
   inline operator int64_t() const noexcept(false);
   /**
@@ -305,7 +309,6 @@ public:
    *
    * @return The double value.
    * @exception simdjson_error(INCORRECT_TYPE) if the JSON element is not a number
-   * @exception simdjson_error(NUMBER_OUT_OF_RANGE) if the integer doesn't fit in 64 bits or is negative
    */
   inline operator double() const noexcept(false);
   /**
@@ -451,6 +454,22 @@ public:
    */
   inline simdjson_result<element> at_key_case_insensitive(std::string_view key) const noexcept;
 
+  /**
+   * operator< defines a total order for element allowing to use them in
+   * ordered C++ STL containers
+   *
+   * @return TRUE if the key appears before the other one in the tape
+   */
+  inline bool operator<(const element &other) const noexcept;
+
+  /**
+   * operator== allows to verify if two element values reference the
+   * same JSON item
+   *
+   * @return TRUE if the two values references the same JSON element
+   */
+  inline bool operator==(const element &other) const noexcept;
+
   /** @private for debugging. Prints out the root element. */
   inline bool dump_raw_tape(std::ostream &out) const noexcept;
 

include/simdjson/dom/jsonparser.h

@@ -1,119 +0,0 @@
-// TODO Remove this -- deprecated API and files
-
-#ifndef SIMDJSON_DOM_JSONPARSER_H
-#define SIMDJSON_DOM_JSONPARSER_H
-
-#include "simdjson/dom/base.h"
-#include "simdjson/dom/parser.h"
-#include "simdjson/dom/element.h"
-
-namespace simdjson {
-
-//
-// C API (json_parse and build_parsed_json) declarations
-//
-
-#ifndef SIMDJSON_DISABLE_DEPRECATED_API
-[[deprecated("Use parser.parse() instead")]]
-inline int json_parse(const uint8_t *buf, size_t len, dom::parser &parser, bool realloc_if_needed = true) noexcept {
-  error_code code = parser.parse(buf, len, realloc_if_needed).error();
-  // The deprecated json_parse API is a signal that the user plans to *use* the error code / valid
-  // bits in the parser instead of heeding the result code. The normal parser unsets those in
-  // anticipation of making the error code ephemeral.
-  // Here we put the code back into the parser, until we've removed this method.
-  parser.valid = code == SUCCESS;
-  parser.error = code;
-  return code;
-}
-[[deprecated("Use parser.parse() instead")]]
-inline int json_parse(const char *buf, size_t len, dom::parser &parser, bool realloc_if_needed = true) noexcept {
-  error_code code = parser.parse(buf, len, realloc_if_needed).error();
-  // The deprecated json_parse API is a signal that the user plans to *use* the error code / valid
-  // bits in the parser instead of heeding the result code. The normal parser unsets those in
-  // anticipation of making the error code ephemeral.
-  // Here we put the code back into the parser, until we've removed this method.
-  parser.valid = code == SUCCESS;
-  parser.error = code;
-  return code;
-}
-[[deprecated("Use parser.parse() instead")]]
-inline int json_parse(const std::string &s, dom::parser &parser, bool realloc_if_needed = true) noexcept {
-  error_code code = parser.parse(s.data(), s.length(), realloc_if_needed).error();
-  // The deprecated json_parse API is a signal that the user plans to *use* the error code / valid
-  // bits in the parser instead of heeding the result code. The normal parser unsets those in
-  // anticipation of making the error code ephemeral.
-  // Here we put the code back into the parser, until we've removed this method.
-  parser.valid = code == SUCCESS;
-  parser.error = code;
-  return code;
-}
-[[deprecated("Use parser.parse() instead")]]
-inline int json_parse(const padded_string &s, dom::parser &parser) noexcept {
-  error_code code = parser.parse(s).error();
-  // The deprecated json_parse API is a signal that the user plans to *use* the error code / valid
-  // bits in the parser instead of heeding the result code. The normal parser unsets those in
-  // anticipation of making the error code ephemeral.
-  // Here we put the code back into the parser, until we've removed this method.
-  parser.valid = code == SUCCESS;
-  parser.error = code;
-  return code;
-}
-
-[[deprecated("Use parser.parse() instead")]]
-simdjson_warn_unused inline dom::parser build_parsed_json(const uint8_t *buf, size_t len, bool realloc_if_needed = true) noexcept {
-  dom::parser parser;
-  error_code code = parser.parse(buf, len, realloc_if_needed).error();
-  // The deprecated json_parse API is a signal that the user plans to *use* the error code / valid
-  // bits in the parser instead of heeding the result code. The normal parser unsets those in
-  // anticipation of making the error code ephemeral.
-  // Here we put the code back into the parser, until we've removed this method.
-  parser.valid = code == SUCCESS;
-  parser.error = code;
-  return parser;
-}
-[[deprecated("Use parser.parse() instead")]]
-simdjson_warn_unused inline dom::parser build_parsed_json(const char *buf, size_t len, bool realloc_if_needed = true) noexcept {
-  dom::parser parser;
-  error_code code = parser.parse(buf, len, realloc_if_needed).error();
-  // The deprecated json_parse API is a signal that the user plans to *use* the error code / valid
-  // bits in the parser instead of heeding the result code. The normal parser unsets those in
-  // anticipation of making the error code ephemeral.
-  // Here we put the code back into the parser, until we've removed this method.
-  parser.valid = code == SUCCESS;
-  parser.error = code;
-  return parser;
-}
-[[deprecated("Use parser.parse() instead")]]
-simdjson_warn_unused inline dom::parser build_parsed_json(const std::string &s, bool realloc_if_needed = true) noexcept {
-  dom::parser parser;
-  error_code code = parser.parse(s.data(), s.length(), realloc_if_needed).error();
-  // The deprecated json_parse API is a signal that the user plans to *use* the error code / valid
-  // bits in the parser instead of heeding the result code. The normal parser unsets those in
-  // anticipation of making the error code ephemeral.
-  // Here we put the code back into the parser, until we've removed this method.
-  parser.valid = code == SUCCESS;
-  parser.error = code;
-  return parser;
-}
-[[deprecated("Use parser.parse() instead")]]
-simdjson_warn_unused inline dom::parser build_parsed_json(const padded_string &s) noexcept {
-  dom::parser parser;
-  error_code code = parser.parse(s).error();
-  // The deprecated json_parse API is a signal that the user plans to *use* the error code / valid
-  // bits in the parser instead of heeding the result code. The normal parser unsets those in
-  // anticipation of making the error code ephemeral.
-  // Here we put the code back into the parser, until we've removed this method.
-  parser.valid = code == SUCCESS;
-  parser.error = code;
-  return parser;
-}
-#endif // SIMDJSON_DISABLE_DEPRECATED_API
-
-/** @private We do not want to allow implicit conversion from C string to std::string. */
-int json_parse(const char *buf, dom::parser &parser) noexcept = delete;
-/** @private We do not want to allow implicit conversion from C string to std::string. */
-dom::parser build_parsed_json(const char *buf) noexcept = delete;
-
-} // namespace simdjson
-
-#endif // SIMDJSON_DOM_JSONPARSER_H

include/simdjson/dom/object-inl.h

@@ -5,6 +5,11 @@
 #include "simdjson/dom/object.h"
 #include "simdjson/dom/document.h"
 
+#include "simdjson/dom/element-inl.h"
+#include "simdjson/error-inl.h"
+
+#include <cstring>
+
 namespace simdjson {
 
 //

include/simdjson/dom/object.h

@@ -18,13 +18,16 @@ public:
 
   class iterator {
   public:
-    using value_type = key_value_pair;
+    using value_type = const key_value_pair;
     using difference_type = std::ptrdiff_t;
+    using pointer = void;
+    using reference = value_type;
+    using iterator_category = std::forward_iterator_tag;
 
     /**
      * Get the actual key/value pair
      */
-    inline const value_type operator*() const noexcept;
+    inline reference operator*() const noexcept;
     /**
      * Get the next key/value pair.
      *

include/simdjson/dom/parsedjson.h

@@ -1,17 +0,0 @@
-// TODO Remove this -- deprecated API and files
-
-#ifndef SIMDJSON_DOM_PARSEDJSON_H
-#define SIMDJSON_DOM_PARSEDJSON_H
-
-#include "simdjson/dom/base.h"
-
-namespace simdjson {
-
-/**
- * @deprecated Use `dom::parser` instead.
- */
-using ParsedJson [[deprecated("Use dom::parser instead")]] = dom::parser;
-
-} // namespace simdjson
-
-#endif // SIMDJSON_DOM_PARSEDJSON_H

include/simdjson/dom/parsedjson_iterator-inl.h

@@ -1,540 +0,0 @@
-#ifndef SIMDJSON_PARSEDJSON_ITERATOR_INL_H
-#define SIMDJSON_PARSEDJSON_ITERATOR_INL_H
-
-#include "simdjson/dom/base.h"
-#include "simdjson/dom/parsedjson_iterator.h"
-#include "simdjson/internal/tape_ref-inl.h"
-#include "simdjson/internal/jsonformatutils.h"
-#include <ostream>
-#include <iterator>
-
-#ifndef SIMDJSON_DISABLE_DEPRECATED_API
-
-namespace simdjson {
-
-// VS2017 reports deprecated warnings when you define a deprecated class's methods.
-SIMDJSON_PUSH_DISABLE_WARNINGS
-SIMDJSON_DISABLE_DEPRECATED_WARNING
-
-// Because of template weirdness, the actual class definition is inline in the document class
-simdjson_warn_unused bool dom::parser::Iterator::is_ok() const {
-  return location < tape_length;
-}
-
-// useful for debugging purposes
-size_t dom::parser::Iterator::get_tape_location() const {
-  return location;
-}
-
-// useful for debugging purposes
-size_t dom::parser::Iterator::get_tape_length() const {
-  return tape_length;
-}
-
-// returns the current depth (start at 1 with 0 reserved for the fictitious root
-// node)
-size_t dom::parser::Iterator::get_depth() const {
-  return depth;
-}
-
-// A scope is a series of nodes at the same depth, typically it is either an
-// object ({) or an array ([). The root node has type 'r'.
-uint8_t dom::parser::Iterator::get_scope_type() const {
-  return depth_index[depth].scope_type;
-}
-
-bool dom::parser::Iterator::move_forward() {
-  if (location + 1 >= tape_length) {
-    return false; // we are at the end!
-  }
-
-  if ((current_type == '[') || (current_type == '{')) {
-    // We are entering a new scope
-    depth++;
-    assert(depth < max_depth);
-    depth_index[depth].start_of_scope = location;
-    depth_index[depth].scope_type = current_type;
-  } else if ((current_type == ']') || (current_type == '}')) {
-    // Leaving a scope.
-    depth--;
-  } else if (is_number()) {
-    // these types use 2 locations on the tape, not just one.
-    location += 1;
-  }
-
-  location += 1;
-  current_val = doc.tape[location];
-  current_type = uint8_t(current_val >> 56);
-  return true;
-}
-
-void dom::parser::Iterator::move_to_value() {
-  // assume that we are on a key, so move by 1.
-  location += 1;
-  current_val = doc.tape[location];
-  current_type = uint8_t(current_val >> 56);
-}
-
-bool dom::parser::Iterator::move_to_key(const char *key) {
-    if (down()) {
-      do {
-        const bool right_key = (strcmp(get_string(), key) == 0);
-        move_to_value();
-        if (right_key) {
-          return true;
-        }
-      } while (next());
-      up();
-    }
-    return false;
-}
-
-bool dom::parser::Iterator::move_to_key_insensitive(
-    const char *key) {
-    if (down()) {
-      do {
-        const bool right_key = (simdjson_strcasecmp(get_string(), key) == 0);
-        move_to_value();
-        if (right_key) {
-          return true;
-        }
-      } while (next());
-      up();
-    }
-    return false;
-}
-
-bool dom::parser::Iterator::move_to_key(const char *key,
-                                                       uint32_t length) {
-  if (down()) {
-    do {
-      bool right_key = ((get_string_length() == length) &&
-                        (memcmp(get_string(), key, length) == 0));
-      move_to_value();
-      if (right_key) {
-        return true;
-      }
-    } while (next());
-    up();
-  }
-  return false;
-}
-
-bool dom::parser::Iterator::move_to_index(uint32_t index) {
-  if (down()) {
-    uint32_t i = 0;
-    for (; i < index; i++) {
-      if (!next()) {
-        break;
-      }
-    }
-    if (i == index) {
-      return true;
-    }
-    up();
-  }
-  return false;
-}
-
-bool dom::parser::Iterator::prev() {
-  size_t target_location = location;
-  to_start_scope();
-  size_t npos = location;
-  if (target_location == npos) {
-    return false; // we were already at the start
-  }
-  size_t oldnpos;
-  // we have that npos < target_location here
-  do {
-    oldnpos = npos;
-    if ((current_type == '[') || (current_type == '{')) {
-      // we need to jump
-      npos = uint32_t(current_val);
-    } else {
-      npos = npos + ((current_type == 'd' || current_type == 'l') ? 2 : 1);
-    }
-  } while (npos < target_location);
-  location = oldnpos;
-  current_val = doc.tape[location];
-  current_type = uint8_t(current_val >> 56);
-  return true;
-}
-
-bool dom::parser::Iterator::up() {
-  if (depth == 1) {
-    return false; // don't allow moving back to root
-  }
-  to_start_scope();
-  // next we just move to the previous value
-  depth--;
-  location -= 1;
-  current_val = doc.tape[location];
-  current_type = uint8_t(current_val >> 56);
-  return true;
-}
-
-bool dom::parser::Iterator::down() {
-  if (location + 1 >= tape_length) {
-    return false;
-  }
-  if ((current_type == '[') || (current_type == '{')) {
-    size_t npos = uint32_t(current_val);
-    if (npos == location + 2) {
-      return false; // we have an empty scope
-    }
-    depth++;
-    assert(depth < max_depth);
-    location = location + 1;
-    depth_index[depth].start_of_scope = location;
-    depth_index[depth].scope_type = current_type;
-    current_val = doc.tape[location];
-    current_type = uint8_t(current_val >> 56);
-    return true;
-  }
-  return false;
-}
-
-void dom::parser::Iterator::to_start_scope() {
-  location = depth_index[depth].start_of_scope;
-  current_val = doc.tape[location];
-  current_type = uint8_t(current_val >> 56);
-}
-
-inline void dom::parser::Iterator::rewind() {
-    while (up())
-    ;
-}
-
-
-bool dom::parser::Iterator::next() {
-  size_t npos;
-  if ((current_type == '[') || (current_type == '{')) {
-    // we need to jump
-    npos = uint32_t(current_val);
-  } else {
-    npos = location + (is_number() ? 2 : 1);
-  }
-  uint64_t next_val = doc.tape[npos];
-  uint8_t next_type = uint8_t(next_val >> 56);
-  if ((next_type == ']') || (next_type == '}')) {
-    return false; // we reached the end of the scope
-  }
-  location = npos;
-  current_val = next_val;
-  current_type = next_type;
-  return true;
-}
-dom::parser::Iterator::Iterator(const dom::parser &pj) noexcept(false)
-    : doc(pj.doc)
-{
-#if SIMDJSON_EXCEPTIONS
-  if (!pj.valid) { throw simdjson_error(pj.error); }
-#else
-  if (!pj.valid) { return; } //  abort() usage is forbidden in the library
-#endif
-
-  max_depth = pj.max_depth();
-  depth_index = new scopeindex_t[max_depth + 1];
-  depth_index[0].start_of_scope = location;
-  current_val = doc.tape[location++];
-  current_type = uint8_t(current_val >> 56);
-  depth_index[0].scope_type = current_type;
-  tape_length = size_t(current_val & internal::JSON_VALUE_MASK);
-  if (location < tape_length) {
-    // If we make it here, then depth_capacity must >=2, but the compiler
-    // may not know this.
-    current_val = doc.tape[location];
-    current_type = uint8_t(current_val >> 56);
-    depth++;
-    assert(depth < max_depth);
-    depth_index[depth].start_of_scope = location;
-    depth_index[depth].scope_type = current_type;
-  }
-}
-dom::parser::Iterator::Iterator(
-    const dom::parser::Iterator &o) noexcept
-    : doc(o.doc),
-    max_depth(o.depth),
-    depth(o.depth),
-    location(o.location),
-    tape_length(o.tape_length),
-    current_type(o.current_type),
-    current_val(o.current_val)
-{
-  depth_index = new scopeindex_t[max_depth+1];
-  std::memcpy(depth_index, o.depth_index, (depth + 1) * sizeof(depth_index[0]));
-}
-
-dom::parser::Iterator::~Iterator() noexcept {
-  if (depth_index) { delete[] depth_index; }
-}
-
-bool dom::parser::Iterator::print(std::ostream &os, bool escape_strings) const {
-  if (!is_ok()) {
-    return false;
-  }
-  switch (current_type) {
-  case '"': // we have a string
-    os << '"';
-    if (escape_strings) {
-      os << internal::escape_json_string(std::string_view(get_string(), get_string_length()));
-    } else {
-      // was: os << get_string();, but given that we can include null chars, we
-      // have to do something crazier:
-      std::copy(get_string(), get_string() + get_string_length(), std::ostream_iterator<char>(os));
-    }
-    os << '"';
-    break;
-  case 'l': // we have a long int
-    os << get_integer();
-    break;
-  case 'u':
-    os << get_unsigned_integer();
-    break;
-  case 'd':
-    os << get_double();
-    break;
-  case 'n': // we have a null
-    os << "null";
-    break;
-  case 't': // we have a true
-    os << "true";
-    break;
-  case 'f': // we have a false
-    os << "false";
-    break;
-  case '{': // we have an object
-  case '}': // we end an object
-  case '[': // we start an array
-  case ']': // we end an array
-    os << char(current_type);
-    break;
-  default:
-    return false;
-  }
-  return true;
-}
-
-bool dom::parser::Iterator::move_to(const char *pointer,
-                                                   uint32_t length) {
-  char *new_pointer = nullptr;
-  if (pointer[0] == '#') {
-    // Converting fragment representation to string representation
-    new_pointer = new char[length];
-    uint32_t new_length = 0;
-    for (uint32_t i = 1; i < length; i++) {
-      if (pointer[i] == '%' && pointer[i + 1] == 'x') {
-#if __cpp_exceptions
-        try {
-#endif
-          int fragment =
-              std::stoi(std::string(&pointer[i + 2], 2), nullptr, 16);
-          if (fragment == '\\' || fragment == '"' || (fragment <= 0x1F)) {
-            // escaping the character
-            new_pointer[new_length] = '\\';
-            new_length++;
-          }
-          new_pointer[new_length] = char(fragment);
-          i += 3;
-#if __cpp_exceptions
-        } catch (std::invalid_argument &) {
-          delete[] new_pointer;
-          return false; // the fragment is invalid
-        }
-#endif
-      } else {
-        new_pointer[new_length] = pointer[i];
-      }
-      new_length++;
-    }
-    length = new_length;
-    pointer = new_pointer;
-  }
-
-  // saving the current state
-  size_t depth_s = depth;
-  size_t location_s = location;
-  uint8_t current_type_s = current_type;
-  uint64_t current_val_s = current_val;
-
-  rewind(); // The json pointer is used from the root of the document.
-
-  bool found = relative_move_to(pointer, length);
-  delete[] new_pointer;
-
-  if (!found) {
-    // since the pointer has found nothing, we get back to the original
-    // position.
-    depth = depth_s;
-    location = location_s;
-    current_type = current_type_s;
-    current_val = current_val_s;
-  }
-
-  return found;
-}
-
-inline bool dom::parser::Iterator::move_to(const std::string &pointer) {
-  return move_to(pointer.c_str(), uint32_t(pointer.length()));
-}
-
-inline int64_t dom::parser::Iterator::get_integer() const {
-    if (location + 1 >= tape_length) {
-    return 0; // default value in case of error
-    }
-    return static_cast<int64_t>(doc.tape[location + 1]);
-}
-
-inline uint64_t dom::parser::Iterator::get_unsigned_integer() const {
-    if (location + 1 >= tape_length) {
-    return 0; // default value in case of error
-    }
-    return doc.tape[location + 1];
-}
-
-inline const char * dom::parser::Iterator::get_string() const {
-    return reinterpret_cast<const char *>(
-        doc.string_buf.get() + (current_val & internal::JSON_VALUE_MASK) + sizeof(uint32_t));
-}
-
-inline uint32_t dom::parser::Iterator::get_string_length() const {
-    uint32_t answer;
-    std::memcpy(&answer,
-        reinterpret_cast<const char *>(doc.string_buf.get() +
-                                        (current_val & internal::JSON_VALUE_MASK)),
-        sizeof(uint32_t));
-    return answer;
-}
-
-inline double dom::parser::Iterator::get_double() const {
-    if (location + 1 >= tape_length) {
-    return std::numeric_limits<double>::quiet_NaN(); // default value in
-                                                    // case of error
-    }
-    double answer;
-    std::memcpy(&answer, &doc.tape[location + 1], sizeof(answer));
-    return answer;
-}
-
-bool dom::parser::Iterator::relative_move_to(const char *pointer,
-                                                            uint32_t length) {
-  if (length == 0) {
-    // returns the whole document
-    return true;
-  }
-
-  if (pointer[0] != '/') {
-    // '/' must be the first character
-    return false;
-  }
-
-  // finding the key in an object or the index in an array
-  std::string key_or_index;
-  uint32_t offset = 1;
-
-  // checking for the "-" case
-  if (is_array() && pointer[1] == '-') {
-    if (length != 2) {
-      // the pointer must be exactly "/-"
-      // there can't be anything more after '-' as an index
-      return false;
-    }
-    key_or_index = '-';
-    offset = length; // will skip the loop coming right after
-  }
-
-  // We either transform the first reference token to a valid json key
-  // or we make sure it is a valid index in an array.
-  for (; offset < length; offset++) {
-    if (pointer[offset] == '/') {
-      // beginning of the next key or index
-      break;
-    }
-    if (is_array() && (pointer[offset] < '0' || pointer[offset] > '9')) {
-      // the index of an array must be an integer
-      // we also make sure std::stoi won't discard whitespaces later
-      return false;
-    }
-    if (pointer[offset] == '~') {
-      // "~1" represents "/"
-      if (pointer[offset + 1] == '1') {
-        key_or_index += '/';
-        offset++;
-        continue;
-      }
-      // "~0" represents "~"
-      if (pointer[offset + 1] == '0') {
-        key_or_index += '~';
-        offset++;
-        continue;
-      }
-    }
-    if (pointer[offset] == '\\') {
-      if (pointer[offset + 1] == '\\' || pointer[offset + 1] == '"' ||
-          (pointer[offset + 1] <= 0x1F)) {
-        key_or_index += pointer[offset + 1];
-        offset++;
-        continue;
-      }
-      return false; // invalid escaped character
-    }
-    if (pointer[offset] == '\"') {
-      // unescaped quote character. this is an invalid case.
-      // lets do nothing and assume most pointers will be valid.
-      // it won't find any corresponding json key anyway.
-      // return false;
-    }
-    key_or_index += pointer[offset];
-  }
-
-  bool found = false;
-  if (is_object()) {
-    if (move_to_key(key_or_index.c_str(), uint32_t(key_or_index.length()))) {
-      found = relative_move_to(pointer + offset, length - offset);
-    }
-  } else if (is_array()) {
-    if (key_or_index == "-") { // handling "-" case first
-      if (down()) {
-        while (next())
-          ; // moving to the end of the array
-        // moving to the nonexistent value right after...
-        size_t npos;
-        if ((current_type == '[') || (current_type == '{')) {
-          // we need to jump
-          npos = uint32_t(current_val);
-        } else {
-          npos =
-              location + ((current_type == 'd' || current_type == 'l') ? 2 : 1);
-        }
-        location = npos;
-        current_val = doc.tape[npos];
-        current_type = uint8_t(current_val >> 56);
-        return true; // how could it fail ?
-      }
-    } else { // regular numeric index
-      // The index can't have a leading '0'
-      if (key_or_index[0] == '0' && key_or_index.length() > 1) {
-        return false;
-      }
-      // it cannot be empty
-      if (key_or_index.length() == 0) {
-        return false;
-      }
-      // we already checked the index contains only valid digits
-      uint32_t index = std::stoi(key_or_index);
-      if (move_to_index(index)) {
-        found = relative_move_to(pointer + offset, length - offset);
-      }
-    }
-  }
-
-  return found;
-}
-
-SIMDJSON_POP_DISABLE_WARNINGS
-} // namespace simdjson
-
-#endif // SIMDJSON_DISABLE_DEPRECATED_API
-
-
-#endif // SIMDJSON_PARSEDJSON_ITERATOR_INL_H

include/simdjson/dom/parsedjson_iterator.h

@@ -1,231 +0,0 @@
-// TODO Remove this -- deprecated API and files
-
-#ifndef SIMDJSON_DOM_PARSEDJSON_ITERATOR_H
-#define SIMDJSON_DOM_PARSEDJSON_ITERATOR_H
-
-#include "simdjson/dom/base.h"
-#include "simdjson/dom/parser.h"
-
-#ifndef SIMDJSON_DISABLE_DEPRECATED_API
-
-namespace simdjson {
-/** @private **/
-class [[deprecated("Use the new DOM navigation API instead (see doc/basics.md)")]] dom::parser::Iterator {
-public:
-  inline Iterator(const dom::parser &parser) noexcept(false);
-  inline Iterator(const Iterator &o) noexcept;
-  inline ~Iterator() noexcept;
-
-  inline Iterator& operator=(const Iterator&) = delete;
-
-  inline bool is_ok() const;
-
-  // useful for debugging purposes
-  inline size_t get_tape_location() const;
-
-  // useful for debugging purposes
-  inline size_t get_tape_length() const;
-
-  // returns the current depth (start at 1 with 0 reserved for the fictitious
-  // root node)
-  inline size_t get_depth() const;
-
-  // A scope is a series of nodes at the same depth, typically it is either an
-  // object ({) or an array ([). The root node has type 'r'.
-  inline uint8_t get_scope_type() const;
-
-  // move forward in document order
-  inline bool move_forward();
-
-  // retrieve the character code of what we're looking at:
-  // [{"slutfn are the possibilities
-  inline uint8_t get_type() const {
-      return current_type; // short functions should be inlined!
-  }
-
-  // get the int64_t value at this node; valid only if get_type is "l"
-  inline int64_t get_integer() const;
-
-  // get the value as uint64; valid only if  if get_type is "u"
-  inline uint64_t get_unsigned_integer() const;
-
-  // get the string value at this node (NULL ended); valid only if get_type is "
-  // note that tabs, and line endings are escaped in the returned value (see
-  // print_with_escapes) return value is valid UTF-8, it may contain NULL chars
-  // within the string: get_string_length determines the true string length.
-  inline const char *get_string() const;
-
-  // return the length of the string in bytes
-  inline uint32_t get_string_length() const;
-
-  // get the double value at this node; valid only if
-  // get_type() is "d"
-  inline double get_double() const;
-
-  inline bool is_object_or_array() const { return is_object() || is_array(); }
-
-  inline bool is_object() const { return get_type() == '{'; }
-
-  inline bool is_array() const { return get_type() == '['; }
-
-  inline bool is_string() const { return get_type() == '"'; }
-
-  // Returns true if the current type of the node is an signed integer.
-  // You can get its value with `get_integer()`.
-  inline bool is_integer() const { return get_type() == 'l'; }
-
-  // Returns true if the current type of the node is an unsigned integer.
-  // You can get its value with `get_unsigned_integer()`.
-  //
-  // NOTE:
-  // Only a large value, which is out of range of a 64-bit signed integer, is
-  // represented internally as an unsigned node. On the other hand, a typical
-  // positive integer, such as 1, 42, or 1000000, is as a signed node.
-  // Be aware this function returns false for a signed node.
-  inline bool is_unsigned_integer() const { return get_type() == 'u'; }
-  // Returns true if the current type of the node is a double floating-point number.
-  inline bool is_double() const { return get_type() == 'd'; }
-  // Returns true if the current type of the node is a number (integer or floating-point).
-  inline bool is_number() const {
-      return is_integer() || is_unsigned_integer() || is_double();
-  }
-  // Returns true if the current type of the node is a bool with true value.
-  inline bool is_true() const { return get_type() == 't'; }
-  // Returns true if the current type of the node is a bool with false value.
-  inline bool is_false() const { return get_type() == 'f'; }
-  // Returns true if the current type of the node is null.
-  inline bool is_null() const { return get_type() == 'n'; }
-  // Returns true if the type byte represents an object of an array
-  static bool is_object_or_array(uint8_t type) {
-      return ((type == '[') || (type == '{'));
-  }
-
-  // when at {, go one level deep, looking for a given key
-  // if successful, we are left pointing at the value,
-  // if not, we are still pointing at the object ({)
-  // (in case of repeated keys, this only finds the first one).
-  // We seek the key using C's strcmp so if your JSON strings contain
-  // NULL chars, this would trigger a false positive: if you expect that
-  // to be the case, take extra precautions.
-  // Furthermore, we do the comparison character-by-character
-  // without taking into account Unicode equivalence.
-  inline bool move_to_key(const char *key);
-
-  // as above, but case insensitive lookup (strcmpi instead of strcmp)
-  inline bool move_to_key_insensitive(const char *key);
-
-  // when at {, go one level deep, looking for a given key
-  // if successful, we are left pointing at the value,
-  // if not, we are still pointing at the object ({)
-  // (in case of repeated keys, this only finds the first one).
-  // The string we search for can contain NULL values.
-  // Furthermore, we do the comparison character-by-character
-  // without taking into account Unicode equivalence.
-  inline bool move_to_key(const char *key, uint32_t length);
-
-  // when at a key location within an object, this moves to the accompanying
-  // value (located next to it). This is equivalent but much faster than
-  // calling "next()".
-  inline void move_to_value();
-
-  // when at [, go one level deep, and advance to the given index.
-  // if successful, we are left pointing at the value,
-  // if not, we are still pointing at the array ([)
-  inline bool move_to_index(uint32_t index);
-
-  // Moves the iterator to the value corresponding to the json pointer.
-  // Always search from the root of the document.
-  // if successful, we are left pointing at the value,
-  // if not, we are still pointing the same value we were pointing before the
-  // call. The json pointer follows the rfc6901 standard's syntax:
-  // https://tools.ietf.org/html/rfc6901 However, the standard says "If a
-  // referenced member name is not unique in an object, the member that is
-  // referenced is undefined, and evaluation fails". Here we just return the
-  // first corresponding value. The length parameter is the length of the
-  // jsonpointer string ('pointer').
-  inline bool move_to(const char *pointer, uint32_t length);
-
-  // Moves the iterator to the value corresponding to the json pointer.
-  // Always search from the root of the document.
-  // if successful, we are left pointing at the value,
-  // if not, we are still pointing the same value we were pointing before the
-  // call. The json pointer implementation follows the rfc6901 standard's
-  // syntax: https://tools.ietf.org/html/rfc6901 However, the standard says
-  // "If a referenced member name is not unique in an object, the member that
-  // is referenced is undefined, and evaluation fails". Here we just return
-  // the first corresponding value.
-  inline bool move_to(const std::string &pointer);
-
-  private:
-  // Almost the same as move_to(), except it searches from the current
-  // position. The pointer's syntax is identical, though that case is not
-  // handled by the rfc6901 standard. The '/' is still required at the
-  // beginning. However, contrary to move_to(), the URI Fragment Identifier
-  // Representation is not supported here. Also, in case of failure, we are
-  // left pointing at the closest value it could reach. For these reasons it
-  // is private. It exists because it is used by move_to().
-  inline bool relative_move_to(const char *pointer, uint32_t length);
-
-  public:
-  // throughout return true if we can do the navigation, false
-  // otherwise
-
-  // Within a given scope (series of nodes at the same depth within either an
-  // array or an object), we move forward.
-  // Thus, given [true, null, {"a":1}, [1,2]], we would visit true, null, {
-  // and [. At the object ({) or at the array ([), you can issue a "down" to
-  // visit their content. valid if we're not at the end of a scope (returns
-  // true).
-  inline bool next();
-
-  // Within a given scope (series of nodes at the same depth within either an
-  // array or an object), we move backward.
-  // Thus, given [true, null, {"a":1}, [1,2]], we would visit ], }, null, true
-  // when starting at the end of the scope. At the object ({) or at the array
-  // ([), you can issue a "down" to visit their content.
-  // Performance warning: This function is implemented by starting again
-  // from the beginning of the scope and scanning forward. You should expect
-  // it to be relatively slow.
-  inline bool prev();
-
-  // Moves back to either the containing array or object (type { or [) from
-  // within a contained scope.
-  // Valid unless we are at the first level of the document
-  inline bool up();
-
-  // Valid if we're at a [ or { and it starts a non-empty scope; moves us to
-  // start of that deeper scope if it not empty. Thus, given [true, null,
-  // {"a":1}, [1,2]], if we are at the { node, we would move to the "a" node.
-  inline bool down();
-
-  // move us to the start of our current scope,
-  // a scope is a series of nodes at the same level
-  inline void to_start_scope();
-
-  inline void rewind();
-
-
-
-  // print the node we are currently pointing at
-  inline bool print(std::ostream &os, bool escape_strings = true) const;
-
-  private:
-  const document &doc;
-  size_t max_depth{};
-  size_t depth{};
-  size_t location{}; // our current location on a tape
-  size_t tape_length{};
-  uint8_t current_type{};
-  uint64_t current_val{};
-  typedef struct {
-      size_t start_of_scope;
-      uint8_t scope_type;
-  } scopeindex_t;
-
-  scopeindex_t *depth_index{};
-};
-
-} // namespace simdjson
-#endif // SIMDJSON_DISABLE_DEPRECATED_API
-
-#endif // SIMDJSON_DOM_PARSEDJSON_ITERATOR_H

include/simdjson/dom/parser-inl.h

@@ -8,9 +8,11 @@
 
 #include "simdjson/error-inl.h"
 #include "simdjson/padded_string-inl.h"
+#include "simdjson/dom/document_stream-inl.h"
 #include "simdjson/dom/element-inl.h"
 
 #include <climits>
+#include <cstring> /* memcmp */
 
 namespace simdjson {
 namespace dom {
@@ -90,10 +92,14 @@ inline simdjson_result<size_t> parser::read_file(const std::string &path) noexce
 }
 
 inline simdjson_result<element> parser::load(const std::string &path) & noexcept {
+  return load_into_document(doc, path);
+}
+
+inline simdjson_result<element> parser::load_into_document(document& provided_doc, const std::string &path) & noexcept {
   size_t len;
   auto _error = read_file(path).get(len);
   if (_error) { return _error; }
-  return parse(loaded_bytes.get(), len, false);
+  return parse_into_document(provided_doc, loaded_bytes.get(), len, false);
 }
 
 inline simdjson_result<document_stream> parser::load_many(const std::string &path, size_t batch_size) noexcept {
@@ -119,8 +125,14 @@ inline simdjson_result<element> parser::parse_into_document(document& provided_d
       _loaded_bytes_capacity = len;
     }
     std::memcpy(static_cast<void *>(loaded_bytes.get()), buf, len);
+    buf = reinterpret_cast<const uint8_t*>(loaded_bytes.get());
   }
-  _error = implementation->parse(realloc_if_needed ? reinterpret_cast<const uint8_t*>(loaded_bytes.get()): buf, len, provided_doc);
+
+  if((len >= 3) && (std::memcmp(buf, "\xEF\xBB\xBF", 3) == 0)) {
+    buf += 3;
+    len -= 3;
+  }
+  _error = implementation->parse(buf, len, provided_doc);
 
   if (_error) { return _error; }
 
@@ -157,6 +169,10 @@ simdjson_inline simdjson_result<element> parser::parse(const padded_string_view
 
 inline simdjson_result<document_stream> parser::parse_many(const uint8_t *buf, size_t len, size_t batch_size) noexcept {
   if(batch_size < MINIMAL_BATCH_SIZE) { batch_size = MINIMAL_BATCH_SIZE; }
+  if((len >= 3) && (std::memcmp(buf, "\xEF\xBB\xBF", 3) == 0)) {
+    buf += 3;
+    len -= 3;
+  }
   return document_stream(*this, buf, len, batch_size);
 }
 inline simdjson_result<document_stream> parser::parse_many(const char *buf, size_t len, size_t batch_size) noexcept {

include/simdjson/dom/parser.h

@@ -95,6 +95,53 @@ public:
    */
   inline simdjson_result<element> load(const std::string &path) & noexcept;
   inline simdjson_result<element> load(const std::string &path) &&  = delete ;
+
+  /**
+   * Load a JSON document from a file into a provide document instance and return a temporary reference to it.
+   * It is similar to the function `load` except that instead of parsing into the internal
+   * `document` instance associated with the parser, it allows the user to provide a document
+   * instance.
+   *
+   *   dom::parser parser;
+   *   dom::document doc;
+   *   element doc_root = parser.load_into_document(doc, "jsonexamples/twitter.json");
+   *
+   * The function is eager: the file's content is loaded in memory inside the parser instance
+   * and immediately parsed. The file can be deleted after the `parser.load_into_document` call.
+   *
+   * ### IMPORTANT: Document Lifetime
+   *
+   * After the call to load_into_document, the parser is no longer needed.
+   *
+   * The JSON document lives in the document instance: you must keep the document
+   * instance alive while you navigate through it (i.e., used the returned value from
+   * load_into_document). You are encourage to reuse the document instance
+   * many times with new data to avoid reallocations:
+   *
+   *   dom::document doc;
+   *   element doc_root1 = parser.load_into_document(doc, "jsonexamples/twitter.json");
+   *   //... doc_root1 is a pointer inside doc
+   *   element doc_root2 = parser.load_into_document(doc, "jsonexamples/twitter.json");
+   *   //... doc_root2 is a pointer inside doc
+   *   // at this point doc_root1 is no longer safe
+   *
+   * Moving the document instance is safe, but it invalidates the element instances. After
+   * moving a document, you can recover safe access to the document root with its `root()` method.
+   *
+   * @param doc The document instance where the parsed data will be stored (on success).
+   * @param path The path to load.
+   * @return The document, or an error:
+   *         - IO_ERROR if there was an error opening or reading the file.
+   *           Be mindful that on some 32-bit systems,
+   *           the file size might be limited to 2 GB.
+   *         - MEMALLOC if the parser does not have enough capacity and memory allocation fails.
+   *         - CAPACITY if the parser does not have enough capacity and len > max_capacity.
+   *         - other json errors if parsing fails. You should not rely on these errors to always the same for the
+   *           same document: they may vary under runtime dispatch (so they may vary depending on your system and hardware).
+   */
+  inline simdjson_result<element> load_into_document(document& doc, const std::string &path) & noexcept;
+  inline simdjson_result<element> load_into_document(document& doc, const std::string &path) && =delete;
+
   /**
    * Parse a JSON document and return a temporary reference to it.
    *
@@ -254,6 +301,8 @@ public:
    * And, possibly, no document many have been parsed when the `parser.load_many(path)` function
    * returned.
    *
+   * If there is a UTF-8 BOM, the parser skips it.
+   *
    * ### Format
    *
    * The file must contain a series of one or more JSON documents, concatenated into a single
@@ -346,6 +395,8 @@ public:
    *     cout << std::string(doc["title"]) << endl;
    *   }
    *
+   * If there is a UTF-8 BOM, the parser skips it.
+   *
    * ### Format
    *
    * The buffer must contain a series of one or more JSON documents, concatenated into a single