version bump

* [utf8-validator] eliminate unnecessary comparison from must_be_2_3_continuation

* Fix comment in

.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

@@ -38,7 +38,7 @@ jobs:
         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

@@ -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
@@ -27,12 +27,11 @@ 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') }}
-          ctest --output-on-failure -LE explicitonly -j
       - name: Use cmake with undefined sanitizer
         run: |
           mkdir builddebugundefsani &&

.github/workflows/ubuntu20.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/ubuntu22-clang13.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-clang14.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-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

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

@@ -3,7 +3,7 @@
         {"column": 95 },
         {"column": 120 }
     ],
-    "files.trimTrailingWhitespace": false,
+    "files.trimTrailingWhitespace": true,
     "files.associations": {
         ".clangd": "yaml",
         "array": "cpp",
@@ -99,6 +99,5 @@
         "shared_mutex": "cpp",
         "ranges": "cpp",
         "span": "cpp"
-    },
-    "editor.trimAutoWhitespace": true
+    }
 }

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.3
+    VERSION 3.6.4
     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 "19.0.0" CACHE STRING "simdjson library version")
+set(SIMDJSON_LIB_SOVERSION "19" 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}")

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.3"
+PROJECT_NUMBER         = "3.6.4"
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a

README.md

@@ -29,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)
@@ -40,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)
@@ -66,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
@@ -93,6 +96,7 @@ int main(void) {
    100 results.
   ```
 
+
 Documentation
 -------------
 
@@ -104,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
 -------------------
@@ -163,6 +168,7 @@ 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.
 
 About simdjson
 --------------
@@ -171,7 +177,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.
 

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_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/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/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/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,7 +114,6 @@ 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")

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)

doc/basics.md

@@ -30,11 +30,13 @@ An overview of what you need to know to use simdjson, with examples.
   - [Dynamic Number Types](#dynamic-number-types)
   - [Raw Strings](#raw-strings)
   - [General Direct Access to the Raw JSON String](#general-direct-access-to-the-raw-json-string)
+  - [Storing Directly into an Existing String Instance](#storing-directly-into-an-existing-string-instance)
   - [Thread Safety](#thread-safety)
   - [Standard Compliance](#standard-compliance)
   - [Backwards Compatibility](#backwards-compatibility)
   - [Examples](#examples)
   - [Performance Tips](#performance-tips)
+  - [Further Reading](#further-reading)
 
 
 Requirements
@@ -85,7 +87,7 @@ include(FetchContent)
 FetchContent_Declare(
   simdjson
   GIT_REPOSITORY https://github.com/simdjson/simdjson.git
-  GIT_TAG  tags/v0.9.6
+  GIT_TAG  tags/v3.6.0
   GIT_SHALLOW TRUE)
 
 FetchContent_MakeAvailable(simdjson)
@@ -179,8 +181,8 @@ strcpy(json, "[1]");
 ondemand::document doc = parser.iterate(json, strlen(json), sizeof(json));
 ```
 
-The simdjson library will also accept `std::string` instances, as long as the `capacity()` of
-the string exceeds the `size()` by at least `SIMDJSON_PADDING`. You can increase the `capacity()` with the `reserve()` function of your strings.
+The simdjson library will also accept `std::string` instances. If the provided
+reference is non-const, it will allocate padding as needed.
 
 You can copy your data directly on a `simdjson::padded_string` as follows:
 
@@ -218,7 +220,8 @@ This means that while you iterate an array, or search for a field in an object,
 walking through the original JSON text, merrily reading commas and colons and brackets to make sure
 you get where you are going. This is the key to On Demand's performance: since it's just an iterator,
 it lets you parse values as you use them. And particularly, it lets you *skip* values you do not want
-to use.
+to use. On Demand is also ideally suited when you want to capture part of the document without parsing it
+immediately (e.g., see [Raw Strings](#raw-strings)).
 
 We refer to "On Demand" as a front-end component since it is an interface between the
 low-level parsing functions and the user. It hides much of the complexity of parsing JSON
@@ -253,7 +256,8 @@ copy the data into their own favorite class instances (e.g., alternatives to `st
 
 A `std::string_view` instance is effectively just a pointer to a region in memory representing
 a string. In simdjson, we return `std::string_view` instances that either point within the
-input string you parsed, or to a temporary string buffer inside our parser class instances.
+input string you parsed (when using [raw Strings](#raw-strings)), or to a temporary string buffer inside
+our parser class instances that is valid until the parser object is destroyed or you use it to parse another document.
 When using `std::string_view` instances, it is your responsibility to ensure that
 `std::string_view` instance does not outlive the pointed-to memory (e.g., either the input
 buffer or the parser instance). Furthermore, some operations reset the string buffer
@@ -261,6 +265,7 @@ inside our parser instances: e.g., when we parse a new document. Thus a `std::st
 is often best viewed as a temporary string value that is tied to the document you are parsing.
 At the cost of some memory allocation, you may convert your `std::string_view` instances for long-term storage into `std::string` instances:
 `std::string mycopy(view)` (C++17) or  `std::string mycopy(view.begin(), view.end())` (prior to C++17).
+For convenience, we also allow [storing an escaped string directly into an existing string instance](#storing-directly-into-an-existing-string-instance).
 
 The `std::string_view` class has become standard as part of C++17 but it is not always available
 on compilers which only supports C++11. When we detect that `string_view` is natively
@@ -355,7 +360,7 @@ support for users who avoid exceptions. See [the simdjson error handling documen
 * **Field Access:** To get the value of the "foo" field in an object, use `object["foo"]`. This will
   scan through the object looking for the field with the matching string, doing a character-by-character
   comparison. It may generate the error `simdjson::NO_SUCH_FIELD` if there is no such key in the object, it may throw an exception (see [Error Handling](#error-handling)). For efficiency reason, you should avoid looking up the same field repeatedly: e.g., do
-  not do `object["foo"]` followed by `object["foo"]` with the same `object` instance. Keep in mind that On Demand does not buffer or save the result of the parsing: if you repeatedly access `object["foo"]`, then it must repeatedly seek the key and parse the content. The library does not provide a distinct function to check if a key is present, instead we recommend you attempt to access the key: e.g., by doing `ondemand::value val{}; if (!object["foo"].get(val)) {...}`, you have that `val` contains the requested value inside the if clause.  It is your responsibility as a user to temporarily keep a reference to the value (`auto v = object["foo"]`), or to consume the content and store it in your own data structures. If you consume an
+  not do `object["foo"]` followed by `object["foo"]` with the same `object` instance. For best performance, you should try to query the keys in the same order they appear in the document. If you need several keys and you cannot predict the order they will appear in, it is recommended to iterate through all keys `for(auto field : object) {...}`.  Keep in mind that On Demand does not buffer or save the result of the parsing: if you repeatedly access `object["foo"]`, then it must repeatedly seek the key and parse the content. The library does not provide a distinct function to check if a key is present, instead we recommend you attempt to access the key: e.g., by doing `ondemand::value val{}; if (!object["foo"].get(val)) {...}`, you have that `val` contains the requested value inside the if clause.  It is your responsibility as a user to temporarily keep a reference to the value (`auto v = object["foo"]`), or to consume the content and store it in your own data structures. If you consume an
   object twice: `std::string_view(object["foo"]` followed by `std::string_view(object["foo"]` then your code
   is in error. Furthermore, you can only consume one field at a time, on the same object. The
   value instance you get from  `content["bids"]` becomes invalid when you call `content["asks"]`.
@@ -370,7 +375,11 @@ support for users who avoid exceptions. See [the simdjson error handling documen
   > as a key, it will not be recognized. This is not generally a problem.  Nevertheless, if you do need
   > to support escaped keys, the method `unescaped_key()` provides the desired unescaped keys by
   > parsing and writing out the unescaped keys to a string buffer and returning a `std::string_view`
-  > instance. You should expect a performance penalty when using `unescaped_key()`.
+  > instance. The `unescaped_key` takes an optional Boolean value: passing it true will decode invalid
+  > Unicode sequences with replacement, meaning that the decoding always succeeds but bogus Unicode
+  > replacement characters are inserted. In general, you should expect a performance penalty
+  > when using `unescaped_key()` compared to `key()` because of the string processing: the `key()`
+  > function just points inside the source JSON document.
   >
   > ```c++
   > auto json = R"({"k\u0065y": 1})"_padded;
@@ -414,8 +423,10 @@ support for users who avoid exceptions. See [the simdjson error handling documen
   step through each value in the JSON array.
 
   If you know the type of the value, you can cast it right there, too! `for (double value : array) { ... }`.
-* **Object Iteration:** You can iterate through an object's fields, as well: `for (auto field : object) { ... }`
-  - `field.unescaped_key()` will get you the unescaped key string.
+
+  You may also use explicit iterators: `for(auto i = array.begin(); i != array.end(); i++) {}`. You can check that an array is empty with the condition `auto i = array.begin(); if(i == array.end()) {...}`.
+* **Object Iteration:** You can iterate through an object's fields, as well: `for (auto field : object) { ... }`. You may also use explicit iterators : `for(auto i = object.begin(); i != object.end(); i++) { auto field = *i; .... }`. You can check that an object is empty with the condition `auto i = object.begin(); if(i == object.end()) {...}`.
+  - `field.unescaped_key()` will get you the unescaped key string. E.g., the JSON string `"\u00e1"` becomes the Unicode string `á`. Optionally,  you pass `true` as a parameter to the `unescaped_key` method if you want invalid escape sequences to be replaced by a default replacement character (e.g., `\ud800\ud801\ud811`): otherwise bad escape sequences lead to an immediate error.
   - `field.value()` will get you the value, which you can then use all these other methods on.
 * **Array Index:** Because it is forward-only, you cannot look up an array element by index by index. Instead,
   you should iterate through the array and keep an index yourself.
@@ -535,9 +546,7 @@ support for users who avoid exceptions. See [the simdjson error handling documen
 * **Tree Walking and JSON Element Types:** Sometimes you don't necessarily have a document
   with a known type, and are trying to generically inspect or walk over JSON elements.
   You can also represent arbitrary JSON values with
-  `ondemand::value` instances: it can represent anything except a scalar document (lone number, string, null or Boolean). You can check for scalar documents with the method `scalar()`.
-  You can query the type of a document or a value with the `type()` method.
-  The `type()` method does not consume or validate documents and values, but it tells you whether they are
+  `ondemand::value` instances: it can represent anything except a scalar document (lone number, string, null or Boolean). You can check for scalar documents with the method `scalar()`. You can cast a document that is either an array or an object to an `ondemand::value` instance immediately after you create the document instance: you cannot create a `ondemand::value` instance from a document that has already been accessed as it would mean that you would have two instances of the object or array simultaneously (see [rewinding](#rewinding)). You can query the type of a document or a value with the `type()` method. The `type()` method does not consume or validate documents and values, but it tells you whether they are
   - arrays (`json_type::array`),
   - objects (`json_type::object`)
   - numbers (`json_type::number`),
@@ -1647,9 +1656,9 @@ JSON string to a user-provided buffer:
 
 General Direct Access to the Raw JSON String
 --------------------------------
-If your value is a string, the `raw_json_string` gives you direct access to the unprocess
-string. The simdjson library allows you to have access to the raw underlying JSON
-more generally.
+If your value is a string, the `raw_json_string` you with `get_raw_json_string()` gives you direct access to the unprocessed
+string. But the simdjson library allows you to have access to the raw underlying JSON
+more generally, not just for strings.
 
 The simdjson library makes explicit assumptions about types. For examples, numbers
 must be integers (up to 64-bit integers) or binary64 floating-point numbers. Some users
@@ -1682,9 +1691,9 @@ string_view token = obj["value"].raw_json_token();
 
 The `raw_json_token()` should be fast and free of allocation.
 
-If you value is an array or an object, `raw_json_token()` returns effectively a single
+If your value is an array or an object, `raw_json_token()` returns effectively a single
 character (`[`) or (`}`) which is not very useful. For arrays and objects, we have another
-method called `raw_json()` which consumes (traverse) the array or the object.
+method called `raw_json()` which consumes (traverses) the array or the object.
 
 ```C++
 simdjson::ondemand::parser parser;
@@ -1716,6 +1725,82 @@ obj.reset(); // revise the object
 uint64_t x = obj["value"]; // gives me 123
 ```
 
+You can use `raw_json()` with the values inside an array and object. When
+calling `raw_json()` on an untyped value, it acts as `raw_json()` when the
+value is an array or an object. Otherwise, it acts as `raw_json_token()`.
+It is useful if you do not care for the type of the value and just wants a
+string representation.
+
+```C++
+  auto json = R"( [1,2,"fds", {"a":1}, [1,344]] )"_padded;
+  ondemand::parser parser;
+  ondemand::document doc = parser.iterate(json);
+  size_t counter = 0;
+  for(auto array: doc) {
+    std::string_view raw = array.raw_json();
+    // will capture "1", "2", "\"fds\"", "{\"a\":1}", "[1,344]"
+  }
+```
+
+```C++
+  auto json = R"( {"key1":1,"key2":2,"key3":"fds", "key4":{"a":1}, "key5":[1,344]} )"_padded;
+  ondemand::parser parser;
+  ondemand::document doc = parser.iterate(json);
+  size_t counter = 0;
+  for(auto key_value: doc.get_object()) {
+    std::string_view raw = key_value.value().raw_json();
+    // will capture "1", "2", "\"fds\"", "{\"a\":1}", "[1,344]"
+  }
+```
+
+
+Storing Directly into an Existing String Instance
+-----------------------------------------------------
+
+The simdjson library favours  the use of `std::string_view` instances because
+it tends to lead to better performance due to causing fewer memory allocations.
+However, they are cases where you need to store a string result in an `std::string``
+instance. You can do so with a templated version of the `to_string()` method which takes as
+a parameter a reference to an `std::string`.
+
+```C++
+  auto json = R"({
+  "name": "Daniel",
+  "age": 42
+})"_padded;
+  ondemand::parser parser;
+  ondemand::document doc = parser.iterate(json);
+  std::string name;
+  doc["name"].get_string(name);
+```
+
+The same routine can be written without exceptions handling:
+
+```C++
+  std::string name;
+  auto err = doc["name"].get_string(name);
+  if(err) { /* handle error */ }
+```
+
+The `std::string` instance, once created, is independent. Unlike our `std::string_view` instances,
+it does not point at data that is within our `parser` instance. The same caveat applies: you should
+only consume a JSON string once.
+
+Because `get_string()` is a template that requires a type that can be assigned an `std::string`, you
+can use it with features such as `std::optional`:
+
+```C++
+  auto json = R"({ "foo1": "3.1416" } )"_padded;
+  ondemand::parser parser;
+  ondemand::document doc = parser.iterate(json);
+  std::optional<std::string> value;
+  if(doc["foo1"].get_string(value)) { /* error */ }
+  // value was populated with "3.1416"
+```
+
+You should be mindful of the trade-off: allocating multiple
+`std::string` instances can become expensive.
+
 Thread Safety
 -------------
 
@@ -1944,6 +2029,79 @@ bool example() {
 }
 ```
 
+* Example 3: CRT
+
+```C++
+
+bool example() {
+  padded_string padded_input_json = R"([
+	{ "monitor": [
+		{ "id": "monitor",		"type": "toggle",		"label": "monitor"			},
+		{ "id": "profile",		"type": "selector",		"label": "collection"		},
+		{ "id": "overlay",		"type": "selector",		"label": "overlay"			},
+		{ "id": "zoom",			"type": "toggleSlider",	"label": "zoom"				}
+	] },
+
+	{ "crt": [
+		{ "id": "system",		"type": "multi",		"label": "system",		"choices": "PAL, NTSC"	},
+		{ "type": "spacer" },
+		{ "id": "brightness",	"type": "slider",		"icon": "brightness"		},
+		{ "id": "contrast",		"type": "slider",		"icon": "contrast"			},
+		{ "id": "saturation",	"type": "slider",		"icon": "saturation"		},
+		{ "type": "spacer" },
+		{ "id": "overscan",		"type": "toggleSlider",	"label": "overscan"			},
+		{ "type": "spacer" },
+		{ "id": "emulation",	"type": "toggle",		"label": "CRT emulation"	},
+		{ "type": "spacer" },
+		{ "id": "curve",		"type": "toggleSlider",	"label": "curve"			},
+		{ "id": "bleed",		"type": "toggleSlider",	"label": "bleed"			},
+		{ "id": "vignette",		"type": "toggleSlider",	"label": "vignette"			},
+		{ "id": "scanlines",	"type": "toggleSlider",	"label": "scanlines"		},
+		{ "id": "gridlines",	"type": "toggleSlider",	"label": "gridlines"		},
+		{ "id": "glow",			"type": "toggleSlider",	"label": "glow"				},
+		{ "id": "flicker",		"type": "toggleSlider",	"label": "flicker"			},
+		{ "id": "noise",		"type": "toggleSlider",	"label": "noise"			},
+    {}
+	] }
+])"_padded;
+  auto parser = ondemand::parser{};
+  auto doc = parser.iterate(padded_input_json);
+  auto root_array = doc.get_array();
+  // the root should be an object, not an array, but that's the JSON we are
+  // given.
+  for (ondemand::object node : root_array) {
+    // We know that we are going to have just one element in the object.
+    for (auto field : node) {
+      std::cout << "\n\ntop level:" << field.key() << std::endl;
+      // You can get a proper std::string_view for the key with:
+      // std::string_view key = field.unescaped_key();
+      // and second for-range loop to get child-elements here
+      for (ondemand::object inner_object : field.value()) {
+        auto i = inner_object.begin();
+        if (i == inner_object.end()) {
+          std::cout << "empty object" << std::endl;
+          continue;
+        } else {
+          for (; i != inner_object.end(); ++i) {
+            auto inner_field = *i;
+            std::cout << '"' << inner_field.key()
+                      << "\" : " << inner_field.value() << ", ";
+            // You can get proper std::string_view for the key and value with:
+            // std::string_view inner_key = field.unescaped_key();
+            // std::string_view value_str = field.value();
+          }
+        }
+        std::cout << std::endl;
+      }
+      // You can break here if you only want just the first element.
+      // break;
+    }
+  }
+  return true;
+}
+```
+
+
 
 Performance Tips
 --------
@@ -1969,4 +2127,10 @@ Performance Tips
 	std::string_view year = data["year"];
 	std::string_view rating = data["rating"];
   ```
-- To better understand the operation of your On Demand parser, and whether it is performing as well as you think it should be, there is a  logger feature built in to simdjson! To use it, define the pre-processor directive `SIMDJSON_VERBOSE_LOGGING` prior to including the `simdjson.h` header, which enables logging in simdjson. Run your code. It may generate a lot of logging output; adding printouts from your application that show each section may be helpful. The log's output will show step-by-step information on state, buffer pointer position, depth, and key retrieval status. Importantly, unless `SIMDJSON_VERBOSE_LOGGING` is defined, logging is entirely disabled and thus carries no overhead.
+- To better understand the operation of your On Demand parser, and whether it is performing as well as you think it should be, there is a  logger feature built in to simdjson! To use it, define the pre-processor directive `SIMDJSON_VERBOSE_LOGGING` prior to including the `simdjson.h` header, which enables logging in simdjson. Run your code. It may generate a lot of logging output; adding printouts from your application that show each section may be helpful. The log's output will show step-by-step information on state, buffer pointer position, depth, and key retrieval status. Importantly, unless `SIMDJSON_VERBOSE_LOGGING` is defined, logging is entirely disabled and thus carries no overhead.
+
+Further reading
+--------
+
+
+- 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)

file.txt

@@ -1,277 +0,0 @@
-number of iterations 3000 
-
-| Original (jsonexamples/twitter-padded-numbers.json) 773
-|- 18-digit numbers (jsonexamples/twitter18.json) 757
-|- 8-digit numbers (jsonexamples/twitter8.json) 766
-|- 1-digit numbers (jsonexamples/twitter1.json) 544
-|  |- strings -> no backslashes (jsonexamples/twitter1-nobackslash.json) 499
-|     |- strings -> no utf8 (jsonexamples/twitter1-nobackslash-noutf8.json) 489
-|        |- strings -> empty strings (jsonexamples/twitter1-emptystring.json) 351
-|           |- no number/bool/null -> all strings (jsonexamples/twitter-allstrings.json) 216
-|              |- no objects -> all arrays (jsonexamples/twitter-allstrings-arrays.json) 427
-|                 |- arrays -> no nested arrays (jsonexamples/twitter-allstrings-flatarray.json) 3
-
-jsonexamples/twitter-padded-numbers.json
-========================================
-    10306 blocks -     659626 bytes - 55262 structurals (  8.4 %)
-special blocks with: utf8      2289 ( 22.2 %) - escape       604 (  5.9 %) - 0 structurals      1270 ( 12.3 %) - 1+ structurals      9037 ( 87.7 %) - 8+ structurals      2576 ( 25.0 %) - 16+ structurals         0 (  0.0 %)
-special block flips: utf8      1096 ( 10.6 %) - escape       646 (  6.3 %) - 0 structurals       932 (  9.0 %) - 1+ structurals       932 (  9.0 %) - 8+ structurals      2843 ( 27.6 %) - 16+ structurals         0 (  0.0 %)
-
-All Stages (excluding allocation)
-|    Speed        :  20.7212 ns per block ( 97.66%) -   0.3238 ns per byte -   3.8647 ns per structural -   3.0885 GB/s
-|    Cycles       :  64.1524 per block    ( 97.86%) -   1.0024 per byte    -  11.9652 per structural    -    3.096 GHz est. frequency
-|    Instructions : 200.2565 per block    (100.00%) -   3.1291 per byte    -  37.3502 per structural    -    3.122 per cycle
-|    Misses       :     873 branch misses ( 93.08%) - 0 cache misses (  0.00%) - 28032.00 cache references
-|- Stage 1
-|    Speed        :   6.0073 ns per block ( 28.31%) -   0.0939 ns per byte -   1.1204 ns per structural -  10.6534 GB/s
-|    Cycles       :  18.6130 per block    ( 28.39%) -   0.2908 per byte    -   3.4715 per structural    -    3.098 GHz est. frequency
-|    Instructions :  61.8107 per block    ( 30.87%) -   0.9658 per byte    -  11.5284 per structural    -    3.321 per cycle
-|    Misses       :      93 branch misses (  9.92%) - 0 cache misses (  0.00%) - 12229.00 cache references
-|- Stage 2
-|    Speed        :  14.6555 ns per block ( 69.07%) -   0.2290 ns per byte -   2.7334 ns per structural -   4.3668 GB/s
-|    Cycles       :  45.3587 per block    ( 69.19%) -   0.7088 per byte    -   8.4599 per structural    -    3.095 GHz est. frequency
-|    Instructions : 138.4458 per block    ( 69.13%) -   2.1633 per byte    -  25.8217 per structural    -    3.052 per cycle
-|    Misses       :     773 branch misses ( 82.42%) - 0 cache misses (  0.00%) - 15925.00 cache references
-
-4682.2 documents parsed per second (best)
-
-jsonexamples/twitter18.json
-===========================
-    10306 blocks -     659626 bytes - 55262 structurals (  8.4 %)
-special blocks with: utf8      2289 ( 22.2 %) - escape       604 (  5.9 %) - 0 structurals      1270 ( 12.3 %) - 1+ structurals      9037 ( 87.7 %) - 8+ structurals      2585 ( 25.1 %) - 16+ structurals         0 (  0.0 %)
-special block flips: utf8      1096 ( 10.6 %) - escape       646 (  6.3 %) - 0 structurals       932 (  9.0 %) - 1+ structurals       932 (  9.0 %) - 8+ structurals      2847 ( 27.6 %) - 16+ structurals         0 (  0.0 %)
-
-All Stages (excluding allocation)
-|    Speed        :  21.1739 ns per block ( 93.63%) -   0.3309 ns per byte -   3.9492 ns per structural -   3.0225 GB/s
-|    Cycles       :  65.5570 per block    ( 97.40%) -   1.0244 per byte    -  12.2271 per structural    -    3.096 GHz est. frequency
-|    Instructions : 205.6160 per block    (100.00%) -   3.2129 per byte    -  38.3498 per structural    -    3.136 per cycle
-|    Misses       :     856 branch misses ( 97.20%) - 0 cache misses (  0.00%) - 28297.00 cache references
-|- Stage 1
-|    Speed        :   5.9968 ns per block ( 26.52%) -   0.0937 ns per byte -   1.1185 ns per structural -  10.6720 GB/s
-|    Cycles       :  18.5808 per block    ( 27.61%) -   0.2903 per byte    -   3.4655 per structural    -    3.098 GHz est. frequency
-|    Instructions :  61.8107 per block    ( 30.06%) -   0.9658 per byte    -  11.5284 per structural    -    3.327 per cycle
-|    Misses       :     103 branch misses ( 11.70%) - 0 cache misses (  0.00%) - 12271.00 cache references
-|- Stage 2
-|    Speed        :  15.0964 ns per block ( 66.75%) -   0.2359 ns per byte -   2.8157 ns per structural -   4.2393 GB/s
-|    Cycles       :  46.7271 per block    ( 69.43%) -   0.7301 per byte    -   8.7151 per structural    -    3.095 GHz est. frequency
-|    Instructions : 143.8053 per block    ( 69.94%) -   2.2470 per byte    -  26.8213 per structural    -    3.078 per cycle
-|    Misses       :     757 branch misses ( 85.96%) - 0 cache misses (  0.00%) - 16107.00 cache references
-
-4582.1 documents parsed per second (best)
-
-jsonexamples/twitter8.json
-==========================
-    10306 blocks -     659626 bytes - 55262 structurals (  8.4 %)
-special blocks with: utf8      2289 ( 22.2 %) - escape       604 (  5.9 %) - 0 structurals      1270 ( 12.3 %) - 1+ structurals      9037 ( 87.7 %) - 8+ structurals      2576 ( 25.0 %) - 16+ structurals         0 (  0.0 %)
-special block flips: utf8      1096 ( 10.6 %) - escape       646 (  6.3 %) - 0 structurals       932 (  9.0 %) - 1+ structurals       932 (  9.0 %) - 8+ structurals      2843 ( 27.6 %) - 16+ structurals         0 (  0.0 %)
-
-All Stages (excluding allocation)
-|    Speed        :  20.6976 ns per block ( 97.48%) -   0.3234 ns per byte -   3.8603 ns per structural -   3.0920 GB/s
-|    Cycles       :  64.0733 per block    ( 97.72%) -   1.0012 per byte    -  11.9504 per structural    -    3.096 GHz est. frequency
-|    Instructions : 200.2565 per block    (100.00%) -   3.1291 per byte    -  37.3502 per structural    -    3.125 per cycle
-|    Misses       :     860 branch misses ( 91.48%) - 0 cache misses (  0.00%) - 28700.00 cache references
-|- Stage 1
-|    Speed        :   6.0103 ns per block ( 28.31%) -   0.0939 ns per byte -   1.1210 ns per structural -  10.6481 GB/s
-|    Cycles       :  18.6231 per block    ( 28.40%) -   0.2910 per byte    -   3.4734 per structural    -    3.099 GHz est. frequency
-|    Instructions :  61.8107 per block    ( 30.87%) -   0.9658 per byte    -  11.5284 per structural    -    3.319 per cycle
-|    Misses       :     102 branch misses ( 10.85%) - 0 cache misses (  0.00%) - 11933.00 cache references
-|- Stage 2
-|    Speed        :  14.6407 ns per block ( 68.95%) -   0.2288 ns per byte -   2.7307 ns per structural -   4.3712 GB/s
-|    Cycles       :  45.3059 per block    ( 69.10%) -   0.7079 per byte    -   8.4501 per structural    -    3.095 GHz est. frequency
-|    Instructions : 138.4458 per block    ( 69.13%) -   2.1633 per byte    -  25.8217 per structural    -    3.056 per cycle
-|    Misses       :     766 branch misses ( 81.48%) - 0 cache misses (  0.00%) - 16566.00 cache references
-
-4687.6 documents parsed per second (best)
-
-jsonexamples/twitter1.json
-==========================
-    10306 blocks -     659626 bytes - 55262 structurals (  8.4 %)
-special blocks with: utf8      2289 ( 22.2 %) - escape       604 (  5.9 %) - 0 structurals      1270 ( 12.3 %) - 1+ structurals      9037 ( 87.7 %) - 8+ structurals      2584 ( 25.1 %) - 16+ structurals         0 (  0.0 %)
-special block flips: utf8      1096 ( 10.6 %) - escape       646 (  6.3 %) - 0 structurals       932 (  9.0 %) - 1+ structurals       932 (  9.0 %) - 8+ structurals      2859 ( 27.7 %) - 16+ structurals         0 (  0.0 %)
-
-All Stages (excluding allocation)
-|    Speed        :  20.1200 ns per block ( 93.76%) -   0.3144 ns per byte -   3.7526 ns per structural -   3.1808 GB/s
-|    Cycles       :  62.2865 per block    ( 97.52%) -   0.9733 per byte    -  11.6172 per structural    -    3.096 GHz est. frequency
-|    Instructions : 194.5666 per block    (100.00%) -   3.0402 per byte    -  36.2889 per structural    -    3.124 per cycle
-|    Misses       :     673 branch misses ( 97.88%) - 0 cache misses (  0.00%) - 28320.00 cache references
-|- Stage 1
-|    Speed        :   6.0046 ns per block ( 27.98%) -   0.0938 ns per byte -   1.1199 ns per structural -  10.6582 GB/s
-|    Cycles       :  18.6140 per block    ( 29.14%) -   0.2909 per byte    -   3.4717 per structural    -    3.100 GHz est. frequency
-|    Instructions :  61.8107 per block    ( 31.77%) -   0.9658 per byte    -  11.5284 per structural    -    3.321 per cycle
-|    Misses       :     113 branch misses ( 16.43%) - 0 cache misses (  0.00%) - 12175.00 cache references
-|- Stage 2
-|    Speed        :  14.0716 ns per block ( 65.57%) -   0.2199 ns per byte -   2.6245 ns per structural -   4.5480 GB/s
-|    Cycles       :  43.5464 per block    ( 68.18%) -   0.6804 per byte    -   8.1219 per structural    -    3.095 GHz est. frequency
-|    Instructions : 132.7559 per block    ( 68.23%) -   2.0744 per byte    -  24.7605 per structural    -    3.049 per cycle
-|    Misses       :     544 branch misses ( 79.11%) - 0 cache misses (  0.00%) - 16212.00 cache references
-
-4822.1 documents parsed per second (best)
-
-jsonexamples/twitter1-nobackslash.json
-======================================
-    10306 blocks -     659626 bytes - 55262 structurals (  8.4 %)
-special blocks with: utf8      2289 ( 22.2 %) - escape         0 (  0.0 %) - 0 structurals      1270 ( 12.3 %) - 1+ structurals      9037 ( 87.7 %) - 8+ structurals      2584 ( 25.1 %) - 16+ structurals         0 (  0.0 %)
-special block flips: utf8      1096 ( 10.6 %) - escape         0 (  0.0 %) - 0 structurals       932 (  9.0 %) - 1+ structurals       932 (  9.0 %) - 8+ structurals      2859 ( 27.7 %) - 16+ structurals         0 (  0.0 %)
-
-All Stages (excluding allocation)
-|    Speed        :  19.3473 ns per block ( 94.75%) -   0.3023 ns per byte -   3.6085 ns per structural -   3.3078 GB/s
-|    Cycles       :  59.8930 per block    ( 97.21%) -   0.9359 per byte    -  11.1707 per structural    -    3.096 GHz est. frequency
-|    Instructions : 191.2882 per block    (100.00%) -   2.9890 per byte    -  35.6774 per structural    -    3.194 per cycle
-|    Misses       :     624 branch misses ( 99.02%) - 2 cache misses ( 30.96%) - 28632.00 cache references
-|- Stage 1
-|    Speed        :   5.9519 ns per block ( 29.15%) -   0.0930 ns per byte -   1.1101 ns per structural -  10.7526 GB/s
-|    Cycles       :  18.4460 per block    ( 29.94%) -   0.2882 per byte    -   3.4404 per structural    -    3.099 GHz est. frequency
-|    Instructions :  61.1661 per block    ( 31.98%) -   0.9558 per byte    -  11.4082 per structural    -    3.316 per cycle
-|    Misses       :      92 branch misses ( 14.60%) - 1 cache misses ( 15.48%) - 12277.00 cache references
-|- Stage 2
-|    Speed        :  13.3283 ns per block ( 65.28%) -   0.2083 ns per byte -   2.4859 ns per structural -   4.8016 GB/s
-|    Cycles       :  41.2453 per block    ( 66.95%) -   0.6445 per byte    -   7.6927 per structural    -    3.095 GHz est. frequency
-|    Instructions : 130.1221 per block    ( 68.02%) -   2.0332 per byte    -  24.2693 per structural    -    3.155 per cycle
-|    Misses       :     499 branch misses ( 79.19%) - 1 cache misses ( 15.48%) - 16358.00 cache references
-
-5014.7 documents parsed per second (best)
-
-jsonexamples/twitter1-nobackslash-noutf8.json
-=============================================
-    10306 blocks -     659626 bytes - 55262 structurals (  8.4 %)
-special blocks with: utf8         0 (  0.0 %) - escape         0 (  0.0 %) - 0 structurals      1270 ( 12.3 %) - 1+ structurals      9037 ( 87.7 %) - 8+ structurals      2584 ( 25.1 %) - 16+ structurals         0 (  0.0 %)
-special block flips: utf8         0 (  0.0 %) - escape         0 (  0.0 %) - 0 structurals       932 (  9.0 %) - 1+ structurals       932 (  9.0 %) - 8+ structurals      2859 ( 27.7 %) - 16+ structurals         0 (  0.0 %)
-
-All Stages (excluding allocation)
-|    Speed        :  18.9506 ns per block ( 97.78%) -   0.2961 ns per byte -   3.5345 ns per structural -   3.3771 GB/s
-|    Cycles       :  58.6756 per block    ( 97.97%) -   0.9168 per byte    -  10.9437 per structural    -    3.096 GHz est. frequency
-|    Instructions : 186.6244 per block    (100.00%) -   2.9161 per byte    -  34.8076 per structural    -    3.181 per cycle
-|    Misses       :     634 branch misses ( 99.08%) - 0 cache misses (  0.00%) - 28596.00 cache references
-|- Stage 1
-|    Speed        :   5.4613 ns per block ( 28.18%) -   0.0853 ns per byte -   1.0186 ns per structural -  11.7184 GB/s
-|    Cycles       :  16.9236 per block    ( 28.26%) -   0.2644 per byte    -   3.1565 per structural    -    3.099 GHz est. frequency
-|    Instructions :  56.5024 per block    ( 30.28%) -   0.8829 per byte    -  10.5383 per structural    -    3.339 per cycle
-|    Misses       :     130 branch misses ( 20.32%) - 0 cache misses (  0.00%) - 12365.00 cache references
-|- Stage 2
-|    Speed        :  13.4108 ns per block ( 69.19%) -   0.2096 ns per byte -   2.5013 ns per structural -   4.7721 GB/s
-|    Cycles       :  41.5073 per block    ( 69.31%) -   0.6486 per byte    -   7.7416 per structural    -    3.095 GHz est. frequency
-|    Instructions : 130.1221 per block    ( 69.72%) -   2.0332 per byte    -  24.2693 per structural    -    3.135 per cycle
-|    Misses       :     489 branch misses ( 76.42%) - 0 cache misses (  0.00%) - 16279.00 cache references
-
-5119.7 documents parsed per second (best)
-
-jsonexamples/twitter1-emptystring.json
-======================================
-    10306 blocks -     659626 bytes - 55262 structurals (  8.4 %)
-special blocks with: utf8         0 (  0.0 %) - escape         0 (  0.0 %) - 0 structurals      1269 ( 12.3 %) - 1+ structurals      9038 ( 87.7 %) - 8+ structurals      2856 ( 27.7 %) - 16+ structurals         0 (  0.0 %)
-special block flips: utf8         0 (  0.0 %) - escape         0 (  0.0 %) - 0 structurals       928 (  9.0 %) - 1+ structurals       928 (  9.0 %) - 8+ structurals      3123 ( 30.3 %) - 16+ structurals         0 (  0.0 %)
-
-All Stages (excluding allocation)
-|    Speed        :  18.0587 ns per block ( 93.58%) -   0.2822 ns per byte -   3.3682 ns per structural -   3.5439 GB/s
-|    Cycles       :  55.9116 per block    ( 97.35%) -   0.8736 per byte    -  10.4282 per structural    -    3.096 GHz est. frequency
-|    Instructions : 183.3181 per block    (100.00%) -   2.8644 per byte    -  34.1909 per structural    -    3.279 per cycle
-|    Misses       :     473 branch misses (101.19%) - 1 cache misses ( 15.11%) - 18833.00 cache references
-|- Stage 1
-|    Speed        :   5.4026 ns per block ( 28.00%) -   0.0844 ns per byte -   1.0077 ns per structural -  11.8457 GB/s
-|    Cycles       :  16.7461 per block    ( 29.16%) -   0.2617 per byte    -   3.1233 per structural    -    3.100 GHz est. frequency
-|    Instructions :  56.5028 per block    ( 30.82%) -   0.8829 per byte    -  10.5384 per structural    -    3.374 per cycle
-|    Misses       :     112 branch misses ( 23.96%) - 0 cache misses (  0.00%) - 10717.00 cache references
-|- Stage 2
-|    Speed        :  12.6022 ns per block ( 65.30%) -   0.1969 ns per byte -   2.3505 ns per structural -   5.0783 GB/s
-|    Cycles       :  39.0031 per block    ( 67.91%) -   0.6094 per byte    -   7.2745 per structural    -    3.095 GHz est. frequency
-|    Instructions : 126.8154 per block    ( 69.18%) -   1.9816 per byte    -  23.6525 per structural    -    3.251 per cycle
-|    Misses       :     351 branch misses ( 75.09%) - 1 cache misses ( 15.11%) - 8120.00 cache references
-
-5372.6 documents parsed per second (best)
-
-jsonexamples/twitter-allstrings.json
-====================================
-    10306 blocks -     659626 bytes - 55262 structurals (  8.4 %)
-special blocks with: utf8         0 (  0.0 %) - escape         0 (  0.0 %) - 0 structurals      1269 ( 12.3 %) - 1+ structurals      9038 ( 87.7 %) - 8+ structurals      2853 ( 27.7 %) - 16+ structurals         0 (  0.0 %)
-special block flips: utf8         0 (  0.0 %) - escape         0 (  0.0 %) - 0 structurals       928 (  9.0 %) - 1+ structurals       928 (  9.0 %) - 8+ structurals      3107 ( 30.1 %) - 16+ structurals         0 (  0.0 %)
-
-All Stages (excluding allocation)
-|    Speed        :  19.6482 ns per block ( 97.20%) -   0.3070 ns per byte -   3.6646 ns per structural -   3.2572 GB/s
-|    Cycles       :  60.8255 per block    ( 97.62%) -   0.9504 per byte    -  11.3446 per structural    -    3.096 GHz est. frequency
-|    Instructions : 183.8463 per block    (100.00%) -   2.8727 per byte    -  34.2895 per structural    -    3.023 per cycle
-|    Misses       :     300 branch misses ( 96.97%) - 0 cache misses (  0.00%) - 18361.00 cache references
-|- Stage 1
-|    Speed        :   5.4053 ns per block ( 26.74%) -   0.0845 ns per byte -   1.0081 ns per structural -  11.8399 GB/s
-|    Cycles       :  16.7545 per block    ( 26.89%) -   0.2618 per byte    -   3.1249 per structural    -    3.100 GHz est. frequency
-|    Instructions :  56.5028 per block    ( 30.73%) -   0.8829 per byte    -  10.5384 per structural    -    3.372 per cycle
-|    Misses       :      98 branch misses ( 31.68%) - 1 cache misses ( 18.41%) - 10786.00 cache references
-|- Stage 2
-|    Speed        :  14.0367 ns per block ( 69.44%) -   0.2193 ns per byte -   2.6180 ns per structural -   4.5593 GB/s
-|    Cycles       :  43.4371 per block    ( 69.71%) -   0.6787 per byte    -   8.1015 per structural    -    3.095 GHz est. frequency
-|    Instructions : 127.3447 per block    ( 69.27%) -   1.9898 per byte    -  23.7513 per structural    -    2.932 per cycle
-|    Misses       :     216 branch misses ( 69.82%) - 0 cache misses (  0.00%) - 7835.00 cache references
-
-4937.9 documents parsed per second (best)
-
-jsonexamples/twitter-allstrings-arrays.json
-===========================================
-    10306 blocks -     659626 bytes - 55262 structurals (  8.4 %)
-special blocks with: utf8         0 (  0.0 %) - escape         0 (  0.0 %) - 0 structurals      1269 ( 12.3 %) - 1+ structurals      9038 ( 87.7 %) - 8+ structurals      2853 ( 27.7 %) - 16+ structurals         0 (  0.0 %)
-special block flips: utf8         0 (  0.0 %) - escape         0 (  0.0 %) - 0 structurals       928 (  9.0 %) - 1+ structurals       928 (  9.0 %) - 8+ structurals      3107 ( 30.1 %) - 16+ structurals         0 (  0.0 %)
-
-All Stages (excluding allocation)
-|    Speed        :  23.6768 ns per block ( 96.29%) -   0.3700 ns per byte -   4.4160 ns per structural -   2.7030 GB/s
-|    Cycles       :  72.7530 per block    ( 95.79%) -   1.1368 per byte    -  13.5693 per structural    -    3.073 GHz est. frequency
-|    Instructions : 225.0789 per block    (100.00%) -   3.5170 per byte    -  41.9798 per structural    -    3.094 per cycle
-|    Misses       :     547 branch misses (104.38%) - 0 cache misses (  0.00%) - 17259.00 cache references
-|- Stage 1
-|    Speed        :   5.4063 ns per block ( 21.99%) -   0.0845 ns per byte -   1.0083 ns per structural -  11.8376 GB/s
-|    Cycles       :  16.7598 per block    ( 22.07%) -   0.2619 per byte    -   3.1259 per structural    -    3.100 GHz est. frequency
-|    Instructions :  56.5028 per block    ( 25.10%) -   0.8829 per byte    -  10.5384 per structural    -    3.371 per cycle
-|    Misses       :     101 branch misses ( 19.27%) - 0 cache misses (  0.00%) - 10570.00 cache references
-|- Stage 2
-|    Speed        :  18.2062 ns per block ( 74.04%) -   0.2845 ns per byte -   3.3957 ns per structural -   3.5152 GB/s
-|    Cycles       :  55.7937 per block    ( 73.46%) -   0.8718 per byte    -  10.4062 per structural    -    3.065 GHz est. frequency
-|    Instructions : 168.5761 per block    ( 74.90%) -   2.6341 per byte    -  31.4414 per structural    -    3.021 per cycle
-|    Misses       :     427 branch misses ( 81.48%) - 0 cache misses (  0.00%) - 6797.00 cache references
-
-4097.7 documents parsed per second (best)
-
-jsonexamples/twitter-allstrings-flatarray.json
-==============================================
-    10306 blocks -     659626 bytes - 49890 structurals (  7.6 %)
-special blocks with: utf8         0 (  0.0 %) - escape         0 (  0.0 %) - 0 structurals      1279 ( 12.4 %) - 1+ structurals      9028 ( 87.6 %) - 8+ structurals      2100 ( 20.4 %) - 16+ structurals         0 (  0.0 %)
-special block flips: utf8         0 (  0.0 %) - escape         0 (  0.0 %) - 0 structurals       946 (  9.2 %) - 1+ structurals       946 (  9.2 %) - 8+ structurals      2668 ( 25.9 %) - 16+ structurals         0 (  0.0 %)
-
-All Stages (excluding allocation)
-|    Speed        :  20.5314 ns per block ( 98.77%) -   0.3208 ns per byte -   4.2417 ns per structural -   3.1171 GB/s
-|    Cycles       :  63.5535 per block    ( 98.95%) -   0.9931 per byte    -  13.1298 per structural    -    3.095 GHz est. frequency
-|    Instructions : 208.9967 per block    (100.00%) -   3.2657 per byte    -  43.1776 per structural    -    3.289 per cycle
-|    Misses       :      94 branch misses ( 99.52%) - 0 cache misses (  0.00%) - 15420.00 cache references
-|- Stage 1
-|    Speed        :   5.3985 ns per block ( 25.97%) -   0.0844 ns per byte -   1.1153 ns per structural -  11.8548 GB/s
-|    Cycles       :  16.7318 per block    ( 26.05%) -   0.2614 per byte    -   3.4567 per structural    -    3.099 GHz est. frequency
-|    Instructions :  56.4917 per block    ( 27.03%) -   0.8827 per byte    -  11.6709 per structural    -    3.376 per cycle
-|    Misses       :      87 branch misses ( 92.11%) - 0 cache misses (  0.00%) - 9889.00 cache references
-|- Stage 2
-|    Speed        :  15.0691 ns per block ( 72.49%) -   0.2355 ns per byte -   3.1132 ns per structural -   4.2470 GB/s
-|    Cycles       :  46.6318 per block    ( 72.61%) -   0.7286 per byte    -   9.6339 per structural    -    3.095 GHz est. frequency
-|    Instructions : 152.5050 per block    ( 72.97%) -   2.3830 per byte    -  31.5067 per structural    -    3.270 per cycle
-|    Misses       :       3 branch misses (  3.18%) - 0 cache misses (  0.00%) - 5610.00 cache references
-
-4725.5 documents parsed per second (best)
-
-jsonexamples/twitter-allstrings-flatobjects.json
-================================================
-    10306 blocks -     659626 bytes - 56091 structurals (  8.5 %)
-special blocks with: utf8         0 (  0.0 %) - escape         0 (  0.0 %) - 0 structurals      1269 ( 12.3 %) - 1+ structurals      9038 ( 87.7 %) - 8+ structurals      2973 ( 28.8 %) - 16+ structurals         0 (  0.0 %)
-special block flips: utf8         0 (  0.0 %) - escape         0 (  0.0 %) - 0 structurals       928 (  9.0 %) - 1+ structurals       928 (  9.0 %) - 8+ structurals      3093 ( 30.0 %) - 16+ structurals         0 (  0.0 %)
-
-All Stages (excluding allocation)
-|    Speed        :  19.4292 ns per block ( 97.71%) -   0.3036 ns per byte -   3.5702 ns per structural -   3.2939 GB/s
-|    Cycles       :  60.1577 per block    ( 97.90%) -   0.9400 per byte    -  11.0543 per structural    -    3.096 GHz est. frequency
-|    Instructions : 181.6747 per block    (100.00%) -   2.8388 per byte    -  33.3836 per structural    -    3.020 per cycle
-|    Misses       :     508 branch misses (100.57%) - 0 cache misses (  0.00%) - 17421.00 cache references
-|- Stage 1
-|    Speed        :   5.4138 ns per block ( 27.22%) -   0.0846 ns per byte -   0.9948 ns per structural -  11.8213 GB/s
-|    Cycles       :  16.7833 per block    ( 27.31%) -   0.2622 per byte    -   3.0840 per structural    -    3.100 GHz est. frequency
-|    Instructions :  56.5028 per block    ( 31.10%) -   0.8829 per byte    -  10.3827 per structural    -    3.367 per cycle
-|    Misses       :      99 branch misses ( 19.60%) - 0 cache misses (  0.00%) - 10517.00 cache references
-|- Stage 2
-|    Speed        :  13.9445 ns per block ( 70.12%) -   0.2179 ns per byte -   2.5624 ns per structural -   4.5895 GB/s
-|    Cycles       :  43.1562 per block    ( 70.23%) -   0.6743 per byte    -   7.9302 per structural    -    3.095 GHz est. frequency
-|    Instructions : 125.1719 per block    ( 68.90%) -   1.9559 per byte    -  23.0010 per structural    -    2.900 per cycle
-|    Misses       :     402 branch misses ( 79.59%) - 0 cache misses (  0.00%) - 6973.00 cache references
-
-4993.6 documents parsed per second (best)
-

include/simdjson/arm64/simd.h

@@ -17,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
@@ -158,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,
@@ -192,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
     )) {}
@@ -283,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
@@ -313,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
@@ -368,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
     )) {}
@@ -486,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
       );

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

@@ -410,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.");
   }
 
   /**
@@ -451,6 +455,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/parser-inl.h

@@ -12,6 +12,7 @@
 #include "simdjson/dom/element-inl.h"
 
 #include <climits>
+#include <cstring> /* memcmp */
 
 namespace simdjson {
 namespace dom {
@@ -91,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 {
@@ -120,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; }
 
@@ -158,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

include/simdjson/error.h

@@ -42,7 +42,7 @@ enum error_code {
   INVALID_URI_FRAGMENT,       ///< Invalid URI fragment
   UNEXPECTED_ERROR,           ///< indicative of a bug in simdjson
   PARSER_IN_USE,              ///< parser is already in use.
-  OUT_OF_ORDER_ITERATION,     ///< tried to iterate an array or object out of order
+  OUT_OF_ORDER_ITERATION,     ///< tried to iterate an array or object out of order (checked when SIMDJSON_DEVELOPMENT_CHECKS=1)
   INSUFFICIENT_PADDING,       ///< The JSON doesn't have enough padding for simdjson to safely parse it.
   INCOMPLETE_ARRAY_OR_OBJECT, ///< The document ends early.
   SCALAR_DOCUMENT_AS_VALUE,   ///< A scalar document is treated as a value.
@@ -51,6 +51,13 @@ enum error_code {
   NUM_ERROR_CODES
 };
 
+/**
+ * It is the convention throughout the code that  the macro SIMDJSON_DEVELOPMENT_CHECKS determines whether
+ * we check for OUT_OF_ORDER_ITERATION. The logic behind it is that these errors only occurs when the code
+ * that was written while breaking some simdjson::ondemand requirement. They should not occur in released
+ * code after these issues were fixed.
+ */
+
 /**
  * Get the error message for the given error code.
  *
@@ -210,11 +217,11 @@ struct simdjson_result : public internal::simdjson_result_base<T> {
    */
   simdjson_inline simdjson_result() noexcept;
   /**
-   * @private Create a new error result.
+   * @private Create a new successful result.
    */
   simdjson_inline simdjson_result(T &&value) noexcept;
   /**
-   * @private Create a new successful result.
+   * @private Create a new error result.
    */
   simdjson_inline simdjson_result(error_code error_code) noexcept;
   /**

include/simdjson/generic/numberparsing.h

@@ -446,11 +446,8 @@ simdjson_inline size_t significant_digits(const uint8_t * start_digits, size_t d
 } // unnamed namespace
 
 /** @private */
-template<typename W>
-error_code slow_float_parsing(simdjson_unused const uint8_t * src, W writer) {
-  double d;
-  if (parse_float_fallback(src, &d)) {
-    writer.append_double(d);
+static error_code slow_float_parsing(simdjson_unused const uint8_t * src, double* answer) {
+  if (parse_float_fallback(src, answer)) {
     return SUCCESS;
   }
   return INVALID_NUMBER(src);
@@ -474,13 +471,13 @@ simdjson_inline error_code write_float(const uint8_t *const src, bool negative,
     // 10000000000000000000000000000000000000000000e+308
     // 3.1415926535897932384626433832795028841971693993751
     //
-    // NOTE: This makes a *copy* of the writer and passes it to slow_float_parsing. This happens
-    // because slow_float_parsing is a non-inlined function. If we passed our writer reference to
-    // it, it would force it to be stored in memory, preventing the compiler from picking it apart
-    // and putting into registers. i.e. if we pass it as reference, it gets slow.
-    // This is what forces the skip_double, as well.
-    error_code error = slow_float_parsing(src, writer);
-    writer.skip_double();
+    // NOTE: We do not pass a reference to the to slow_float_parsing. If we passed our writer
+    // reference to it, it would force it to be stored in memory, preventing the compiler from
+    // picking it apart and putting into registers. i.e. if we pass it as reference,
+    // it gets slow.
+    double d;
+    error_code error = slow_float_parsing(src, &d);
+    writer.append_double(d);
     return error;
   }
   // NOTE: it's weird that the simdjson_unlikely() only wraps half the if, but it seems to get slower any other
@@ -1004,7 +1001,7 @@ simdjson_unused simdjson_inline simdjson_result<double> parse_double(const uint8
       // Skip leading 0.00000 and see if it still overflows
       const uint8_t *start_digits = src + 2;
       while (*start_digits == '0') { start_digits++; }
-      overflow = start_digits-src > 19;
+      overflow = p-start_digits > 19;
     }
   } else {
     overflow = p-src > 19;
@@ -1203,7 +1200,7 @@ simdjson_unused simdjson_inline simdjson_result<double> parse_double_in_string(c
       // Skip leading 0.00000 and see if it still overflows
       const uint8_t *start_digits = src + 2;
       while (*start_digits == '0') { start_digits++; }
-      overflow = start_digits-src > 19;
+      overflow = p-start_digits > 19;
     }
   } else {
     overflow = p-src > 19;

include/simdjson/generic/ondemand/document-inl.h

@@ -68,7 +68,17 @@ simdjson_inline simdjson_result<object> document::start_or_resume_object() noexc
 simdjson_inline simdjson_result<value> document::get_value() noexcept {
   // Make sure we start any arrays or objects before returning, so that start_root_<object/array>()
   // gets called.
-  iter.assert_at_document_depth();
+
+  // It is the convention throughout the code that  the macro `SIMDJSON_DEVELOPMENT_CHECKS` determines whether
+  // we check for OUT_OF_ORDER_ITERATION. Proper on::demand code should never trigger this error.
+#if SIMDJSON_DEVELOPMENT_CHECKS
+  if (!iter.at_root()) { return OUT_OF_ORDER_ITERATION; }
+#endif
+  // assert_at_root() serves two purposes: in Debug mode, whether or not
+  // SIMDJSON_DEVELOPMENT_CHECKS is set or not, it checks that we are at the root of
+  // the document (this will typically be redundant). In release mode, it generates
+  // SIMDJSON_ASSUME statements to allow the compiler to make assumptions.
+  iter.assert_at_root();
   switch (*iter.peek()) {
     case '[': {
       // The following lines check that the document ends with ].
@@ -128,6 +138,10 @@ simdjson_inline simdjson_result<double> document::get_double_in_string() noexcep
 simdjson_inline simdjson_result<std::string_view> document::get_string(bool allow_replacement) noexcept {
   return get_root_value_iterator().get_root_string(true, allow_replacement);
 }
+template <typename string_type>
+simdjson_inline error_code document::get_string(string_type& receiver, bool allow_replacement) noexcept {
+  return get_root_value_iterator().get_root_string(receiver, true, allow_replacement);
+}
 simdjson_inline simdjson_result<std::string_view> document::get_wobbly_string() noexcept {
   return get_root_value_iterator().get_root_wobbly_string(true);
 }
@@ -397,6 +411,11 @@ simdjson_inline simdjson_result<std::string_view> simdjson_result<SIMDJSON_IMPLE
   if (error()) { return error(); }
   return first.get_string(allow_replacement);
 }
+template <typename string_type>
+simdjson_inline error_code simdjson_result<SIMDJSON_IMPLEMENTATION::ondemand::document>::get_string(string_type& receiver, bool allow_replacement) noexcept {
+  if (error()) { return error(); }
+  return first.get_string(receiver, allow_replacement);
+}
 simdjson_inline simdjson_result<std::string_view> simdjson_result<SIMDJSON_IMPLEMENTATION::ondemand::document>::get_wobbly_string() noexcept {
   if (error()) { return error(); }
   return first.get_wobbly_string();
@@ -583,6 +602,8 @@ simdjson_inline simdjson_result<int64_t> document_reference::get_int64_in_string
 simdjson_inline simdjson_result<double> document_reference::get_double() noexcept { return doc->get_root_value_iterator().get_root_double(false); }
 simdjson_inline simdjson_result<double> document_reference::get_double_in_string() noexcept { return doc->get_root_value_iterator().get_root_double(false); }
 simdjson_inline simdjson_result<std::string_view> document_reference::get_string(bool allow_replacement) noexcept { return doc->get_root_value_iterator().get_root_string(false, allow_replacement); }
+template <typename string_type>
+simdjson_inline error_code document_reference::get_string(string_type& receiver, bool allow_replacement) noexcept { return doc->get_root_value_iterator().get_root_string(receiver, false, allow_replacement); }
 simdjson_inline simdjson_result<std::string_view> document_reference::get_wobbly_string() noexcept { return doc->get_root_value_iterator().get_root_wobbly_string(false); }
 simdjson_inline simdjson_result<raw_json_string> document_reference::get_raw_json_string() noexcept { return doc->get_root_value_iterator().get_root_raw_json_string(false); }
 simdjson_inline simdjson_result<bool> document_reference::get_bool() noexcept { return doc->get_root_value_iterator().get_root_bool(false); }
@@ -719,6 +740,11 @@ simdjson_inline simdjson_result<std::string_view> simdjson_result<SIMDJSON_IMPLE
   if (error()) { return error(); }
   return first.get_string(allow_replacement);
 }
+template <typename string_type>
+simdjson_inline error_code simdjson_result<SIMDJSON_IMPLEMENTATION::ondemand::document_reference>::get_string(string_type& receiver, bool allow_replacement) noexcept {
+  if (error()) { return error(); }
+  return first.get_string(receiver, allow_replacement);
+}
 simdjson_inline simdjson_result<std::string_view> simdjson_result<SIMDJSON_IMPLEMENTATION::ondemand::document_reference>::get_wobbly_string() noexcept {
   if (error()) { return error(); }
   return first.get_wobbly_string();

include/simdjson/generic/ondemand/document.h

@@ -100,6 +100,21 @@ public:
    * @returns INCORRECT_TYPE if the JSON value is not a string.
    */
   simdjson_inline simdjson_result<std::string_view> get_string(bool allow_replacement = false) noexcept;
+  /**
+   * Attempts to fill the provided std::string reference with the parsed value of the current string.
+   *
+   * The string is guaranteed to be valid UTF-8.
+   *
+   * Important: a value should be consumed once. Calling get_string() twice on the same value
+   * is an error.
+   *
+   * Performance: This method may be slower than get_string() or get_string(bool) because it may need to allocate memory.
+   * We recommend you avoid allocating an std::string unless you need to.
+   *
+   * @returns INCORRECT_TYPE if the JSON value is not a string. Otherwise, we return SUCCESS.
+   */
+  template <typename string_type>
+  simdjson_inline error_code get_string(string_type& receiver, bool allow_replacement = false) noexcept;
   /**
    * Cast this JSON value to a string.
    *
@@ -131,6 +146,12 @@ public:
   /**
    * Cast this JSON value to a value when the document is an object or an array.
    *
+   * You must not have begun iterating through the object or array. When
+   * SIMDJSON_DEVELOPMENT_CHECKS is set to 1 (which is the case when building in Debug mode
+   * by default), and you have already begun iterating,
+   * you will get an OUT_OF_ORDER_ITERATION error. If you have begun iterating, you can use
+   * rewind() to reset the document to its initial state before calling this method.
+   *
    * @returns A value if a JSON array or object cannot be found.
    * @returns SCALAR_DOCUMENT_AS_VALUE error is the document is a scalar (see is_scalar() function).
    */
@@ -160,13 +181,19 @@ public:
   template<typename T> simdjson_inline simdjson_result<T> get() & 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 ondemand::object, ondemand::array, raw_json_string, std::string_view, uint64_t, "
+      "int64_t, double, and bool. We recommend you use get_double(), get_bool(), get_uint64(), get_int64(), "
+      " get_object(), get_array(), get_raw_json_string(), or get_string() instead of the get template.");
   }
   /** @overload template<typename T> simdjson_result<T> get() & noexcept */
   template<typename T> simdjson_inline simdjson_result<T> get() && 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 ondemand::object, ondemand::array, raw_json_string, std::string_view, uint64_t, "
+      "int64_t, double, and bool. We recommend you use get_double(), get_bool(), get_uint64(), get_int64(), "
+      " get_object(), get_array(), get_raw_json_string(), or get_string() instead of the get template.");
   }
 
   /**
@@ -247,10 +274,15 @@ public:
    */
   simdjson_inline operator bool() noexcept(false);
   /**
-   * Cast this JSON value to a value.
+   * Cast this JSON value to a value when the document is an object or an array.
    *
-   * @returns A value value.
-   * @exception if a JSON value cannot be found
+   * You must not have begun iterating through the object or array. When
+   * SIMDJSON_DEVELOPMENT_CHECKS is defined, and you have already begun iterating,
+   * you will get an OUT_OF_ORDER_ITERATION error. If you have begun iterating, you can use
+   * rewind() to reset the document to its initial state before calling this method.
+   *
+   * @returns A value value if a JSON array or object cannot be found.
+   * @exception SCALAR_DOCUMENT_AS_VALUE error is the document is a scalar (see is_scalar() function).
    */
   simdjson_inline operator value() noexcept(false);
 #endif
@@ -618,6 +650,8 @@ public:
   simdjson_inline simdjson_result<double> get_double() noexcept;
   simdjson_inline simdjson_result<double> get_double_in_string() noexcept;
   simdjson_inline simdjson_result<std::string_view> get_string(bool allow_replacement = false) noexcept;
+  template <typename string_type>
+  simdjson_inline error_code get_string(string_type& receiver, bool allow_replacement = false) noexcept;
   simdjson_inline simdjson_result<std::string_view> get_wobbly_string() noexcept;
   simdjson_inline simdjson_result<raw_json_string> get_raw_json_string() noexcept;
   simdjson_inline simdjson_result<bool> get_bool() noexcept;
@@ -687,6 +721,8 @@ public:
   simdjson_inline simdjson_result<double> get_double() noexcept;
   simdjson_inline simdjson_result<double> get_double_in_string() noexcept;
   simdjson_inline simdjson_result<std::string_view> get_string(bool allow_replacement = false) noexcept;
+  template <typename string_type>
+  simdjson_inline error_code get_string(string_type& receiver, bool allow_replacement = false) noexcept;
   simdjson_inline simdjson_result<std::string_view> get_wobbly_string() noexcept;
   simdjson_inline simdjson_result<SIMDJSON_IMPLEMENTATION::ondemand::raw_json_string> get_raw_json_string() noexcept;
   simdjson_inline simdjson_result<bool> get_bool() noexcept;
@@ -759,6 +795,8 @@ public:
   simdjson_inline simdjson_result<double> get_double() noexcept;
   simdjson_inline simdjson_result<double> get_double_in_string() noexcept;
   simdjson_inline simdjson_result<std::string_view> get_string(bool allow_replacement = false) noexcept;
+  template <typename string_type>
+  simdjson_inline error_code get_string(string_type& receiver, bool allow_replacement = false) noexcept;
   simdjson_inline simdjson_result<std::string_view> get_wobbly_string() noexcept;
   simdjson_inline simdjson_result<SIMDJSON_IMPLEMENTATION::ondemand::raw_json_string> get_raw_json_string() noexcept;
   simdjson_inline simdjson_result<bool> get_bool() noexcept;

include/simdjson/generic/ondemand/document_stream.h

@@ -241,8 +241,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/generic/ondemand/json_iterator.h

@@ -254,6 +254,7 @@ public:
    */
   simdjson_inline simdjson_result<std::string_view> unescape(raw_json_string in, bool allow_replacement) noexcept;
   simdjson_inline simdjson_result<std::string_view> unescape_wobbly(raw_json_string in) noexcept;
+
   simdjson_inline void reenter_child(token_position position, depth_t child_depth) noexcept;
 
   simdjson_inline error_code consume_character(char c) noexcept;

include/simdjson/generic/ondemand/json_type.h

@@ -92,8 +92,6 @@ protected:
    */
   friend class value_iterator;
   template<typename W>
-  friend error_code numberparsing::slow_float_parsing(simdjson_unused const uint8_t * src, W writer);
-  template<typename W>
   friend error_code numberparsing::write_float(const uint8_t *const src, bool negative, uint64_t i, const uint8_t * start_digits, size_t digit_count, int64_t exponent, W &writer);
   template<typename W>
   friend error_code numberparsing::parse_number(const uint8_t *const src, W &writer);

include/simdjson/generic/ondemand/parser-inl.h

@@ -46,6 +46,8 @@ simdjson_warn_unused simdjson_inline error_code parser::allocate(size_t new_capa
 simdjson_warn_unused simdjson_inline simdjson_result<document> parser::iterate(padded_string_view json) & noexcept {
   if (json.padding() < SIMDJSON_PADDING) { return INSUFFICIENT_PADDING; }
 
+  json.remove_utf8_bom();
+
   // Allocate if needed
   if (capacity() < json.length() || !string_buf) {
     SIMDJSON_TRY( allocate(json.length(), max_depth()) );
@@ -68,6 +70,13 @@ simdjson_warn_unused simdjson_inline simdjson_result<document> parser::iterate(s
   return iterate(padded_string_view(json, allocated));
 }
 
+simdjson_warn_unused simdjson_inline simdjson_result<document> parser::iterate(std::string &json) & noexcept {
+  if(json.capacity() - json.size() < SIMDJSON_PADDING) {
+    json.reserve(json.size() + SIMDJSON_PADDING);
+  }
+  return iterate(padded_string_view(json));
+}
+
 simdjson_warn_unused simdjson_inline simdjson_result<document> parser::iterate(const std::string &json) & noexcept {
   return iterate(padded_string_view(json));
 }
@@ -89,6 +98,8 @@ simdjson_warn_unused simdjson_inline simdjson_result<document> parser::iterate(c
 simdjson_warn_unused simdjson_inline simdjson_result<json_iterator> parser::iterate_raw(padded_string_view json) & noexcept {
   if (json.padding() < SIMDJSON_PADDING) { return INSUFFICIENT_PADDING; }
 
+  json.remove_utf8_bom();
+
   // Allocate if needed
   if (capacity() < json.length()) {
     SIMDJSON_TRY( allocate(json.length(), max_depth()) );
@@ -101,6 +112,10 @@ simdjson_warn_unused simdjson_inline simdjson_result<json_iterator> parser::iter
 
 inline simdjson_result<document_stream> parser::iterate_many(const uint8_t *buf, size_t len, size_t batch_size, bool allow_comma_separated) 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;
+  }
   if(allow_comma_separated && batch_size < len) { batch_size = len; }
   return document_stream(*this, buf, len, batch_size, allow_comma_separated);
 }

include/simdjson/generic/ondemand/parser.h

@@ -59,7 +59,7 @@ public:
    * It is expected that the content is a valid UTF-8 file, containing a valid JSON document.
    * Otherwise the iterate method may return an error. In particular, the whole input should be
    * valid: we do not attempt to tolerate incorrect content either before or after a JSON
-   * document.
+   * document. If there is a UTF-8 BOM, the parser skips it.
    *
    * ### IMPORTANT: Validate what you use
    *
@@ -107,6 +107,8 @@ public:
   /** @overload simdjson_result<document> iterate(padded_string_view json) & noexcept */
   simdjson_warn_unused simdjson_result<document> iterate(const std::string &json) & noexcept;
   /** @overload simdjson_result<document> iterate(padded_string_view json) & noexcept */
+  simdjson_warn_unused simdjson_result<document> iterate(std::string &json) & noexcept;
+  /** @overload simdjson_result<document> iterate(padded_string_view json) & noexcept */
   simdjson_warn_unused simdjson_result<document> iterate(const simdjson_result<padded_string> &json) & noexcept;
   /** @overload simdjson_result<document> iterate(padded_string_view json) & noexcept */
   simdjson_warn_unused simdjson_result<document> iterate(const simdjson_result<padded_string_view> &json) & noexcept;
@@ -186,6 +188,7 @@ public:
    * arrays or objects) MUST be separated with ASCII whitespace.
    *
    * The characters inside a JSON document, and between JSON documents, must be valid Unicode (UTF-8).
+   * If there is a UTF-8 BOM, the parser skips it.
    *
    * The documents must not exceed batch_size bytes (by default 1MB) or they will fail to parse.
    * Setting batch_size to excessively large or excessively small values may impact negatively the

include/simdjson/generic/ondemand/value-inl.h

@@ -47,6 +47,10 @@ simdjson_inline simdjson_result<raw_json_string> value::get_raw_json_string() no
 simdjson_inline simdjson_result<std::string_view> value::get_string(bool allow_replacement) noexcept {
   return iter.get_string(allow_replacement);
 }
+template <typename string_type>
+simdjson_inline error_code value::get_string(string_type& receiver, bool allow_replacement) noexcept {
+  return iter.get_string(receiver, allow_replacement);
+}
 simdjson_inline simdjson_result<std::string_view> value::get_wobbly_string() noexcept {
   return iter.get_wobbly_string();
 }
@@ -193,6 +197,26 @@ simdjson_inline std::string_view value::raw_json_token() noexcept {
   return std::string_view(reinterpret_cast<const char*>(iter.peek_start()), iter.peek_start_length());
 }
 
+simdjson_inline simdjson_result<std::string_view> value::raw_json() noexcept {
+  json_type t;
+  SIMDJSON_TRY(type().get(t));
+  switch (t)
+  {
+    case json_type::array: {
+      ondemand::array array;
+      SIMDJSON_TRY(get_array().get(array));
+      return array.raw_json();
+    }
+    case json_type::object: {
+      ondemand::object object;
+      SIMDJSON_TRY(get_object().get(object));
+      return object.raw_json();
+    }
+    default:
+      return raw_json_token();
+  }
+}
+
 simdjson_inline simdjson_result<const char *> value::current_location() noexcept {
   return iter.json_iter().current_location();
 }
@@ -319,6 +343,11 @@ simdjson_inline simdjson_result<std::string_view> simdjson_result<SIMDJSON_IMPLE
   if (error()) { return error(); }
   return first.get_string(allow_replacement);
 }
+template <typename string_type>
+simdjson_inline error_code simdjson_result<SIMDJSON_IMPLEMENTATION::ondemand::value>::get_string(string_type& receiver, bool allow_replacement) noexcept {
+  if (error()) { return error(); }
+  return first.get_string(receiver, allow_replacement);
+}
 simdjson_inline simdjson_result<std::string_view> simdjson_result<SIMDJSON_IMPLEMENTATION::ondemand::value>::get_wobbly_string() noexcept {
   if (error()) { return error(); }
   return first.get_wobbly_string();
@@ -419,6 +448,11 @@ simdjson_inline simdjson_result<std::string_view> simdjson_result<SIMDJSON_IMPLE
   return first.raw_json_token();
 }
 
+simdjson_inline simdjson_result<std::string_view> simdjson_result<SIMDJSON_IMPLEMENTATION::ondemand::value>::raw_json() noexcept {
+  if (error()) { return error(); }
+  return first.raw_json();
+}
+
 simdjson_inline simdjson_result<const char *> simdjson_result<SIMDJSON_IMPLEMENTATION::ondemand::value>::current_location() noexcept {
   if (error()) { return error(); }
   return first.current_location();

include/simdjson/generic/ondemand/value.h

@@ -38,7 +38,10 @@ public:
   template<typename T> simdjson_inline simdjson_result<T> get() 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 ondemand::object, ondemand::array, raw_json_string, std::string_view, uint64_t, "
+      "int64_t, double, and bool. We recommend you use get_double(), get_bool(), get_uint64(), get_int64(), "
+      " get_object(), get_array(), get_raw_json_string(), or get_string() instead of the get template.");
   }
 
   /**
@@ -132,6 +135,21 @@ public:
    */
   simdjson_inline simdjson_result<std::string_view> get_string(bool allow_replacement = false) noexcept;
 
+  /**
+   * Attempts to fill the provided std::string reference with the parsed value of the current string.
+   *
+   * The string is guaranteed to be valid UTF-8.
+   *
+   * Important: a value should be consumed once. Calling get_string() twice on the same value
+   * is an error.
+   *
+   * Performance: This method may be slower than get_string() or get_string(bool) because it may need to allocate memory.
+   * We recommend you avoid allocating an std::string unless you need to.
+   *
+   * @returns INCORRECT_TYPE if the JSON value is not a string. Otherwise, we return SUCCESS.
+   */
+  template <typename string_type>
+  simdjson_inline error_code get_string(string_type& receiver, bool allow_replacement = false) noexcept;
 
   /**
    * Cast this JSON value to a "wobbly" string.
@@ -475,9 +493,21 @@ public:
    * - true
    * - false
    * - null
+   *
+   * See also value::raw_json().
    */
   simdjson_inline std::string_view raw_json_token() noexcept;
 
+  /**
+   * Get a string_view pointing at this value in the JSON document.
+   * If this element is an array or an object, it consumes the array or the object
+   * and returns a string_view instance corresponding to the
+   * array as represented in JSON. It points inside the original document.
+   * If this element is a scalar (string, number, Boolean, null), it returns what
+   * raw_json_token() would return.
+   */
+  simdjson_inline simdjson_result<std::string_view> raw_json() noexcept;
+
   /**
    * Returns the current location in the document if in bounds.
    */
@@ -602,6 +632,8 @@ public:
   simdjson_inline simdjson_result<double> get_double() noexcept;
   simdjson_inline simdjson_result<double> get_double_in_string() noexcept;
   simdjson_inline simdjson_result<std::string_view> get_string(bool allow_replacement = false) noexcept;
+  template <typename string_type>
+  simdjson_inline error_code get_string(string_type& receiver, bool allow_replacement = false) noexcept;
   simdjson_inline simdjson_result<std::string_view> get_wobbly_string() noexcept;
   simdjson_inline simdjson_result<SIMDJSON_IMPLEMENTATION::ondemand::raw_json_string> get_raw_json_string() noexcept;
   simdjson_inline simdjson_result<bool> get_bool() noexcept;
@@ -694,6 +726,7 @@ public:
 
   /** @copydoc simdjson_inline std::string_view value::raw_json_token() const noexcept */
   simdjson_inline simdjson_result<std::string_view> raw_json_token() noexcept;
+  simdjson_inline simdjson_result<std::string_view> raw_json() noexcept;
 
   /** @copydoc simdjson_inline simdjson_result<const char *> current_location() noexcept */
   simdjson_inline simdjson_result<const char *> current_location() noexcept;

include/simdjson/generic/ondemand/value_iterator-inl.h

@@ -513,6 +513,14 @@ simdjson_warn_unused simdjson_inline simdjson_result<bool> value_iterator::parse
 simdjson_warn_unused simdjson_inline simdjson_result<std::string_view> value_iterator::get_string(bool allow_replacement) noexcept {
   return get_raw_json_string().unescape(json_iter(), allow_replacement);
 }
+template <typename string_type>
+simdjson_warn_unused simdjson_inline error_code value_iterator::get_string(string_type& receiver, bool allow_replacement) noexcept {
+  std::string_view content;
+  auto err = get_string(allow_replacement).get(content);
+  if (err) { return err; }
+  receiver = content;
+  return SUCCESS;
+}
 simdjson_warn_unused simdjson_inline simdjson_result<std::string_view> value_iterator::get_wobbly_string() noexcept {
   return get_raw_json_string().unescape_wobbly(json_iter());
 }
@@ -636,6 +644,14 @@ simdjson_inline simdjson_result<number> value_iterator::get_root_number(bool che
 simdjson_warn_unused simdjson_inline simdjson_result<std::string_view> value_iterator::get_root_string(bool check_trailing, bool allow_replacement) noexcept {
   return get_root_raw_json_string(check_trailing).unescape(json_iter(), allow_replacement);
 }
+template <typename string_type>
+simdjson_warn_unused simdjson_inline error_code value_iterator::get_root_string(string_type& receiver, bool check_trailing, bool allow_replacement) noexcept {
+  std::string_view content;
+  auto err = get_root_string(check_trailing, allow_replacement).get(content);
+  if (err) { return err; }
+  receiver = content;
+  return SUCCESS;
+}
 simdjson_warn_unused simdjson_inline simdjson_result<std::string_view> value_iterator::get_root_wobbly_string(bool check_trailing) noexcept {
   return get_root_raw_json_string(check_trailing).unescape_wobbly(json_iter());
 }

include/simdjson/generic/ondemand/value_iterator.h

@@ -296,6 +296,8 @@ public:
    */
 
   simdjson_warn_unused simdjson_inline simdjson_result<std::string_view> get_string(bool allow_replacement) noexcept;
+  template <typename string_type>
+  simdjson_warn_unused simdjson_inline error_code get_string(string_type& receiver, bool allow_replacement) noexcept;
   simdjson_warn_unused simdjson_inline simdjson_result<std::string_view> get_wobbly_string() noexcept;
   simdjson_warn_unused simdjson_inline simdjson_result<raw_json_string> get_raw_json_string() noexcept;
   simdjson_warn_unused simdjson_inline simdjson_result<uint64_t> get_uint64() noexcept;
@@ -312,7 +314,9 @@ public:
   simdjson_warn_unused simdjson_inline simdjson_result<number> get_number() noexcept;
 
   simdjson_warn_unused simdjson_inline simdjson_result<std::string_view> get_root_string(bool check_trailing, bool allow_replacement) noexcept;
-    simdjson_warn_unused simdjson_inline simdjson_result<std::string_view> get_root_wobbly_string(bool check_trailing) noexcept;
+  template <typename string_type>
+  simdjson_warn_unused simdjson_inline error_code get_root_string(string_type& receiver, bool check_trailing, bool allow_replacement) noexcept;
+  simdjson_warn_unused simdjson_inline simdjson_result<std::string_view> get_root_wobbly_string(bool check_trailing) noexcept;
   simdjson_warn_unused simdjson_inline simdjson_result<raw_json_string> get_root_raw_json_string(bool check_trailing) noexcept;
   simdjson_warn_unused simdjson_inline simdjson_result<uint64_t> get_root_uint64(bool check_trailing) noexcept;
   simdjson_warn_unused simdjson_inline simdjson_result<uint64_t> get_root_uint64_in_string(bool check_trailing) noexcept;

include/simdjson/nonstd/string_view.hpp

@@ -6,7 +6,7 @@
 // Distributed under the Boost Software License, Version 1.0.
 // (See accompanying file LICENSE.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 
-#pragma once
+// #pragma once // We remove #pragma once here as it generates a warning in some cases. We rely on the include guard.
 
 #ifndef NONSTD_SV_LITE_H_INCLUDED
 #define NONSTD_SV_LITE_H_INCLUDED
@@ -69,6 +69,10 @@
 # define nssv_CONFIG_NO_STREAM_INSERTION  0
 #endif
 
+#ifndef  nssv_CONFIG_CONSTEXPR11_STD_SEARCH
+# define nssv_CONFIG_CONSTEXPR11_STD_SEARCH  1
+#endif
+
 // Control presence of exception handling (try and auto discover):
 
 #ifndef nssv_CONFIG_NO_EXCEPTIONS
@@ -267,7 +271,7 @@ using std::operator<<;
 # define nssv_HAS_CPP0X  0
 #endif
 
-// Unless defined otherwise below, consider VC14 as C++11 for variant-lite:
+// Unless defined otherwise below, consider VC14 as C++11 for string-view-lite:
 
 #if nssv_COMPILER_MSVC_VER >= 1900
 # undef  nssv_CPP11_OR_GREATER
@@ -434,9 +438,9 @@ using std::operator<<;
 # pragma clang diagnostic ignored "-Wreserved-user-defined-literal"
 # pragma clang diagnostic push
 # pragma clang diagnostic ignored "-Wuser-defined-literals"
-#elif defined(__GNUC__)
-# pragma  GCC  diagnostic push
-# pragma  GCC  diagnostic ignored "-Wliteral-suffix"
+#elif nssv_COMPILER_GNUC_VERSION >= 480
+#  pragma  GCC  diagnostic push
+#  pragma  GCC  diagnostic ignored "-Wliteral-suffix"
 #endif // __clang__
 
 #if nssv_COMPILER_MSVC_VERSION >= 140
@@ -451,8 +455,8 @@ using std::operator<<;
 
 #if defined(__clang__)
 # define nssv_RESTORE_WARNINGS()  _Pragma("clang diagnostic pop")
-#elif defined(__GNUC__)
-# define nssv_RESTORE_WARNINGS()  _Pragma("GCC diagnostic pop")
+#elif nssv_COMPILER_GNUC_VERSION >= 480
+#  define nssv_RESTORE_WARNINGS()  _Pragma("GCC diagnostic pop")
 #elif nssv_COMPILER_MSVC_VERSION >= 140
 # define nssv_RESTORE_WARNINGS()  __pragma(warning(pop ))
 #else
@@ -567,12 +571,31 @@ constexpr const CharT* search( basic_string_view<CharT, Traits> haystack, basic_
 
 // non-recursive:
 
+#if nssv_CONFIG_CONSTEXPR11_STD_SEARCH
+
 template< class CharT, class Traits = std::char_traits<CharT> >
 constexpr const CharT* search( basic_string_view<CharT, Traits> haystack, basic_string_view<CharT, Traits> needle )
 {
     return std::search( haystack.begin(), haystack.end(), needle.begin(), needle.end() );
 }
 
+#else // nssv_CONFIG_CONSTEXPR11_STD_SEARCH
+
+template< class CharT, class Traits = std::char_traits<CharT> >
+nssv_constexpr14 const CharT* search( basic_string_view<CharT, Traits> haystack, basic_string_view<CharT, Traits> needle )
+{
+    while ( needle.size() <= haystack.size() )
+    {
+        if  ( haystack.starts_with(needle) )
+        {
+            return haystack.cbegin();
+        }
+        haystack = basic_string_view<CharT, Traits>{ haystack.begin() + 1, haystack.size() - 1U };
+    }
+    return haystack.cend();
+}
+#endif // nssv_CONFIG_CONSTEXPR11_STD_SEARCH
+
 #endif // OPTIMIZE
 #endif // nssv_CPP11_OR_GREATER && ! nssv_CPP17_OR_GREATER
 
@@ -845,7 +868,7 @@ public:
 
     // find(), 4x:
 
-    nssv_constexpr size_type find( basic_string_view v, size_type pos = 0 ) const nssv_noexcept  // (1)
+    nssv_constexpr14 size_type find( basic_string_view v, size_type pos = 0 ) const nssv_noexcept  // (1)
     {
         return assert( v.size() == 0 || v.data() != nssv_nullptr )
             , pos >= size()

include/simdjson/padded_string_view-inl.h

@@ -2,9 +2,10 @@
 #define SIMDJSON_PADDED_STRING_VIEW_INL_H
 
 #include "simdjson/padded_string_view.h"
-
 #include "simdjson/error-inl.h"
 
+#include <cstring> /* memcmp */
+
 namespace simdjson {
 
 inline padded_string_view::padded_string_view(const char* s, size_t len, size_t capacity) noexcept
@@ -31,6 +32,16 @@ inline size_t padded_string_view::capacity() const noexcept { return _capacity;
 
 inline size_t padded_string_view::padding() const noexcept { return capacity() - length(); }
 
+inline bool padded_string_view::remove_utf8_bom() noexcept {
+  if(length() < 3) { return false; }
+  if (std::memcmp(data(), "\xEF\xBB\xBF", 3) == 0) {
+    remove_prefix(3);
+    _capacity -= 3;
+    return true;
+  }
+  return false;
+}
+
 #if SIMDJSON_EXCEPTIONS
 inline std::ostream& operator<<(std::ostream& out, simdjson_result<padded_string_view> &s) noexcept(false) { return out << s.value(); }
 #endif

include/simdjson/padded_string_view.h

@@ -54,6 +54,13 @@ public:
   /** The number of allocated bytes. */
   inline size_t capacity() const noexcept;
 
+  /**
+   * Remove the UTF-8 Byte Order Mark (BOM) if it exists.
+   *
+   * @return whether a BOM was found and removed
+   */
+  inline bool remove_utf8_bom() noexcept;
+
   /** The amount of padding on the string (capacity() - length()) */
   inline size_t padding() const noexcept;
 

include/simdjson/portability.h

@@ -36,6 +36,8 @@
 #define SIMDJSON_IS_X86_64 1
 #elif defined(__aarch64__) || defined(_M_ARM64)
 #define SIMDJSON_IS_ARM64 1
+#elif defined(__riscv) && __riscv_xlen == 64
+#define SIMDJSON_IS_RISCV64 1
 #elif defined(__PPC64__) || defined(_M_PPC64)
 #if defined(__ALTIVEC__)
 #define SIMDJSON_IS_PPC64_VMX 1
@@ -58,11 +60,8 @@
 
 #if SIMDJSON_IS_32BITS
 #ifndef SIMDJSON_NO_PORTABILITY_WARNING
-#pragma message("The simdjson library is designed \
-for 64-bit processors and it seems that you are not \
-compiling for a known 64-bit platform. All fast kernels \
-will be disabled and performance may be poor. Please \
-use a 64-bit target such as x64, 64-bit ARM or 64-bit PPC.")
+// In the future, we should allow programmers
+// to get warning.
 #endif // SIMDJSON_NO_PORTABILITY_WARNING
 #endif // SIMDJSON_IS_32BITS
 

include/simdjson/simdjson_version.h

@@ -4,7 +4,7 @@
 #define SIMDJSON_SIMDJSON_VERSION_H
 
 /** The version of simdjson being used (major.minor.revision) */
-#define SIMDJSON_VERSION "3.2.3"
+#define SIMDJSON_VERSION "3.6.4"
 
 namespace simdjson {
 enum {
@@ -15,11 +15,11 @@ enum {
   /**
    * The minor version (major.MINOR.revision) of simdjson being used.
    */
-  SIMDJSON_VERSION_MINOR = 2,
+  SIMDJSON_VERSION_MINOR = 6,
   /**
    * The revision (major.minor.REVISION) of simdjson being used.
    */
-  SIMDJSON_VERSION_REVISION = 3
+  SIMDJSON_VERSION_REVISION = 4
 };
 } // namespace simdjson
 

jsonexamples/collect-results.py

@@ -1,263 +0,0 @@
-from itertools import groupby
-from pathlib import Path
-from typing import Any, Iterable, Literal, Optional, OrderedDict, cast
-from io import BufferedWriter, BufferedReader
-import re
-import sys
-
-ContainerState = Literal['orig', 'array', 'flat']
-ScalarState = Literal['orig', '1digit', 'str']
-StringState = Literal['orig', 'unescaped', 'ascii', 'empty']
-CONTAINER_STATES: list[ContainerState] = ['orig', 'array', 'flat']
-SCALAR_STATES: list[ScalarState] = ['orig', '1digit', 'str']
-STRING_STATES: list[StringState] = ['orig', 'unescaped', 'ascii', 'empty']
-
-class Result:
-    class Metric:
-        def __init__(self, name: str, value: float, units: str):
-            self.name = name
-            self.value = value
-            self.units = units
-        
-        def best(self, other: 'Result.Metric'):
-            assert self.name == other.name
-            assert self.units == other.units
-            if self.name == 'Speed':
-                return self if self.value > other.value else other
-            else:
-                return self if self.value < other.value else other
-
-    class Stage:
-        def __init__(self, stage: str):
-            self.stage = stage
-            self.metrics: dict[str, Result.Metric] = {}
-
-        @property
-        def speed(self):
-            return self.metrics['Speed']
-
-        @property
-        def cycles(self):
-            return self.metrics['Cycles']
-
-        @property
-        def instructions(self):
-            return self.metrics['Instructions']
-
-        @property
-        def misses(self):
-            return self.metrics['Misses']
-
-        def _merge_in(self, other: 'Result.Stage'):
-            assert self.stage == other.stage
-            for metric in other.metrics.values():
-                if metric.name not in self.metrics:
-                    self.metrics[metric.name] = metric
-                self.metrics[metric.name] = self.metrics[metric.name].best(metric)
-
-    def __init__(self, json_file: Path):
-        self.json_file = json_file
-        self.stages = dict[str, Result.Stage]()
-        match = re.match(r'(.*)-([^-]*)-([^-]*)-([^-]*)$', json_file.stem)
-        if match:
-            self.base_json_file = match.group(1)
-            assert match.group(2) in CONTAINER_STATES
-            self.container_state: ContainerState = cast(ContainerState, match.group(2))
-            assert match.group(3) in SCALAR_STATES
-            self.scalar_state: ScalarState = cast(ScalarState, match.group(3))
-            assert match.group(4) in STRING_STATES
-            self.string_state: StringState = cast(StringState, match.group(4))
-        else:
-            self.base_json_file = self.json_file.stem
-            self.container_state = 'orig'
-            self.scalar_state = 'orig'
-            self.string_state = 'orig'
-        self.docs_per_second: float = -1
-
-    def __lt__(self, other: 'Result'):
-        if self.base_json_file != other.base_json_file:
-            return self.base_json_file < other.base_json_file
-        if self.container_state != other.container_state:
-            return CONTAINER_STATES.index(self.container_state) < CONTAINER_STATES.index(other.container_state)
-        if self.scalar_state != other.scalar_state:
-            return SCALAR_STATES.index(self.scalar_state) < SCALAR_STATES.index(other.scalar_state)
-        if self.string_state != other.string_state:
-            return STRING_STATES.index(self.string_state) < STRING_STATES.index(other.string_state)
-        return False
-            
-    def merge(self, other: 'Result'):
-        merged = Result(self.json_file)
-        merged._merge_in(self)
-        merged._merge_in(other)
-        return merged
-
-    def _merge_in(self, other: 'Result'):
-        assert self.json_file == other.json_file
-        if other.docs_per_second > self.docs_per_second:
-            self.docs_per_second = other.docs_per_second
-        for stage in other.stages.values():
-            if stage.stage not in self.stages:
-                self.stages[stage.stage] = Result.Stage(stage.stage)
-            self.stages[stage.stage]._merge_in(stage)
-
-    @property
-    def stage1(self):
-        return self.stages['Stage 1']
-
-    @property
-    def stage2(self):
-        return self.stages['Stage 2']
-
-def read_results(results_file: Path):
-    with open(result_file, 'rt') as input:
-        result = None
-        stage = None
-
-        prev_line = None
-        for line in input:
-            if re.match(r'=+$', line):
-                assert result is None
-                assert prev_line is not None
-                result = Result(Path(prev_line.strip()))
-
-            # Stage
-            match = re.match(r'\|-(.+)$', line)
-            if match:
-                assert result is not None
-                stage = Result.Stage(match.group(1).strip())
-                result.stages[stage.stage] = stage
-
-            # Metrics
-            if stage is not None:
-                match = re.match(r'\|([^:]+):\s*([-+0-9.]+)\s+([^(-]+)', line)
-                if match and stage is not None:
-                    metric = Result.Metric(match.group(1).strip(), float(match.group(2)), match.group(3).strip())
-                    stage.metrics[metric.name] = metric
-
-            # Documents per second
-            match = re.match(r'\s*([-+0-9.]+)\s*documents parsed per second', line)
-            if match:
-                assert result is not None
-                result.docs_per_second = float(match.group(1))
-                yield result
-                result = None
-                stage = None
-            
-            prev_line = line
-
-# Merge multiple results for the same file
-all_results = dict[Path, Result]()
-for result_file in sys.argv[1:]:
-    for result in read_results(Path(result_file)):
-        if result.json_file in all_results:
-            all_results[result.json_file] = all_results[result.json_file].merge(result)
-        else:
-            all_results[result.json_file] = result
-
-def print_row(row: Iterable, key_lengths: OrderedDict[str, int], rjust: set[str]):
-    column_iter = iter(row)
-    for (key, width) in key_lengths.items():
-        value = str(next(column_iter))
-        if key in rjust:
-            print(f"| {str(value).rjust(width)} ", end='')
-        else:
-            print(f"| {str(value).ljust(width)} ", end='')
-    print("|")
-
-def print_table(rows: list[OrderedDict], key_lengths: Optional[OrderedDict[str, int]] = None, rjust = set[str]()):
-    if key_lengths is None:
-        key_lengths = OrderedDict[str, int]()
-        for entry in rows:
-            for (key, value) in entry.items():
-                if key not in key_lengths:
-                    key_lengths[key] = len(key)
-                key_lengths[key] = max(key_lengths[key], len(str(value)))
-
-    print_row(list(key_lengths.keys()), key_lengths, rjust)
-    print("|", *[ f"{(':' if key in rjust else '').rjust(len+2, '-')}|" for (key, len) in key_lengths.items() ], sep='')
-
-    for row in rows:
-        print_row(row.values(), key_lengths, rjust)
-
-for (file, results) in groupby(sorted(all_results.values()), lambda r: r.base_json_file):
-    results = [*results]
-    print()
-    print(f"# {file}.json Branch Miss Variants")
-    print()
-    print_table(
-        [
-            OrderedDict([
-                ('Contain',  result.container_state),
-                ('Scalars',  result.scalar_state),
-                ('Strings',  result.string_state),
-                ('Cycles',   '%.4f' % result.stage2.cycles.value),
-                ('Instrs',   '%.4f' % result.stage2.instructions.value),
-                ('Misses',   int(result.stage2.misses.value)),
-                ('Docs/sec', '%.1f' % result.docs_per_second),
-            ])
-            for result in results
-        ],
-        rjust = set(['Cycles', 'Instrs', 'Misses', 'Docs/sec'])
-    )
-    misses = {
-        (r.container_state, r.scalar_state, r.string_state): int(r.stage2.misses.value)
-        for r in results
-    }
-
-    print()
-    print('## Container State Transition Miss Reduction')
-    print()
-    rows = list[OrderedDict[str, object]]()
-    PRINT_STRING_STATES: list[StringState] = [s for s in STRING_STATES if s != 'unescaped']
-    for (i,from_state) in enumerate(CONTAINER_STATES[0:-1]):
-        for to_state in CONTAINER_STATES[i+1:]:
-            rows.append(OrderedDict([
-                ('Contain', f"{from_state} -> {to_state}"),
-                *[
-                    (
-                        f"{scalar_state} {string_state}",
-                        misses[(from_state, scalar_state, string_state)] - misses[(to_state, scalar_state, string_state)]
-                    )
-                    for scalar_state in SCALAR_STATES
-                    for string_state in PRINT_STRING_STATES
-                ]
-            ]))
-    print_table(rows, rjust = [*rows[0].keys()][1:])
-
-    print()
-    print('## Scalar State Transition Miss Reduction')
-    print()
-    rows = list[OrderedDict[str, object]]()
-    for (i,from_state) in enumerate(SCALAR_STATES[0:-1]):
-        for to_state in SCALAR_STATES[i+1:]:
-            rows.append(OrderedDict([
-                ('Scalars', f"{from_state} -> {to_state}"),
-                *[
-                    (
-                        f"{container_state} {string_state}",
-                        misses[(container_state, from_state, string_state)] - misses[(container_state, to_state, string_state)]
-                    )
-                    for container_state in CONTAINER_STATES
-                    for string_state in PRINT_STRING_STATES
-                ]
-            ]))
-    print_table(rows, rjust = [*rows[0].keys()][1:])
-
-    print()
-    print('## String State Transition Miss Reduction')
-    print()
-    rows = list[OrderedDict[str, object]]()
-    for (i,from_state) in enumerate(STRING_STATES[0:-1]):
-        for to_state in STRING_STATES[i+1:]:
-            rows.append(OrderedDict([
-                ('Strings', f"{from_state} -> {to_state}"),
-                *[
-                    (
-                        f"{container_state} {scalar_state}",
-                        misses[(container_state, scalar_state, from_state)] - misses[(container_state, scalar_state, to_state)]
-                    )
-                    for container_state in CONTAINER_STATES
-                    for scalar_state in SCALAR_STATES
-                ]
-            ]))
-    print_table(rows, rjust = [*rows[0].keys()][1:])

jsonexamples/gen-branch-test-variants.py

@@ -1,170 +0,0 @@
-from pathlib import Path
-from typing import Literal
-from io import BufferedWriter, BufferedReader
-import re
-import sys
-
-ContainerState = Literal['orig', 'array', 'flat']
-ScalarState = Literal['orig', '1digit', 'str']
-StringState = Literal['orig', 'unescaped', 'ascii', 'empty']
-CONTAINER_STATES: list[ContainerState] = ['orig', 'array', 'flat']
-SCALAR_STATES: list[ScalarState] = ['orig', '1digit', 'str']
-STRING_STATES: list[StringState] = ['orig', 'unescaped', 'ascii', 'empty']
-
-def right_pad(padded_length: int, b: bytes):
-    assert len(b) <= padded_length
-    return b + b' '*(padded_length-len(b))
-
-def right_pad2(r: bytes, b: bytes):
-    print(f"right_pad({r}, {b})")
-    return right_pad(len(r), b)
-
-class JsonFile:
-    def __init__(self,
-                 original_json_file: Path,
-                 container_state: ContainerState = 'orig',
-                 scalar_state: ScalarState = 'orig',
-                 string_state: StringState = 'orig'):
-        self.original_json_file = original_json_file
-        self.container_state: ContainerState = container_state
-        self.scalar_state: ScalarState = scalar_state
-        self.string_state: StringState = string_state
-
-    @property
-    def path(self):
-        if self.container_state == 'orig' and self.scalar_state == 'orig' and self.string_state == 'orig':
-            return self.original_json_file
-        else:
-            return self.original_json_file.with_stem(f"{self.original_json_file.stem}-{self.container_state}-{self.scalar_state}-{self.string_state}")
-
-    def write(self, force: bool = False):
-        if force or not self.path.exists():
-            with open(self.path, 'wb') as out:
-                self.write_to(out)
-
-    def with_container_state(self, container_state: ContainerState):
-        return JsonFile(self.original_json_file, container_state, self.scalar_state, self.string_state)
-    def with_scalar_state(self, scalar_state: ScalarState):
-        return JsonFile(self.original_json_file, self.container_state, scalar_state, self.string_state)
-    def with_string_state(self, string_state: StringState):
-        return JsonFile(self.original_json_file, self.container_state, self.scalar_state, string_state)    
-
-    def open(self):
-        return open(self.path, 'rb')
-
-    def write_to(self, out: BufferedWriter):
-        if self.string_state == 'unescaped':
-            return self.remove_escapes(self.with_string_state('orig').open(), out)
-        elif self.string_state == 'ascii':
-            return self.remove_utf8(self.with_string_state('unescaped').open(), out)
-        elif self.string_state == 'empty':
-            return self.replace_strings(self.with_string_state('ascii').open(), out, b'""')
-        else:
-            assert self.string_state == 'orig'
-
-        if self.scalar_state == '1digit':
-            return self.replace_numbers(self.with_scalar_state('orig').open(), out, b'0')
-        elif self.scalar_state == 'str':
-            return self.replace_non_strings(self.with_scalar_state('1digit').open(), out, b'""')
-        else:
-            assert self.scalar_state == 'orig'
-
-        if self.container_state == 'array':
-            return self.replace_objects_with_arrays(self.with_container_state('orig').open(), out)
-        elif self.container_state == 'flat':
-            return self.remove_nesting(self.with_container_state('array').open(), out)
-        else:
-            assert self.container_state == 'orig'
-
-        assert self.path.exists()
-
-    def remove_escapes(self, input: BufferedReader, out: BufferedWriter):
-        for line in input:
-            out.write(re.sub(rb'\\(.)', rb'__', line))
-
-    def remove_utf8(self, input: BufferedReader, out: BufferedWriter):
-        for line in input:
-            out.write(bytes([(b if b < 128 else ord('_')) for b in line]))
-
-    def replace_strings(self, input: BufferedReader, out: BufferedWriter, replacement: bytes):
-        for line in input:
-            assert line.find(b'\\') == -1
-            out.write(re.sub(rb'"([^"]*)"', lambda s: right_pad(len(s.group(0)), replacement), line))
-
-    def replace_numbers(self, input: BufferedReader, out: BufferedWriter, replacement: bytes):
-        for line in input:
-            for (non_string, string) in self.split_by_strings(line):
-                out.write(re.sub(rb'\s*[-0-9][-+0-9.eE]*\s*', lambda s: right_pad(len(s.group(0)), replacement), non_string))
-                out.write(string)
-
-    def replace_non_strings(self, input: BufferedReader, out: BufferedWriter, replacement: bytes):
-        for line in input:
-            for (non_string, string) in self.split_by_strings(line):
-                out.write(re.sub(rb'\s*[^,:{}[\] \r\t\n]+\s*', lambda s: right_pad(len(s.group(0)), replacement), non_string))
-                out.write(string)
-
-    def replace_objects_with_arrays(self, input: BufferedReader, out: BufferedWriter):
-        for line in input:
-            for (non_string, string) in self.split_by_strings(line):
-                out.write(non_string.replace(b'{', b'[').replace(b'}', b']').replace(b':', b','))
-                out.write(string)
-
-    def remove_nesting(self, input: BufferedReader, out: BufferedWriter):
-        prev_line = None
-        is_first_line = True
-        lines = iter(input)
-        line = next(lines, None)
-        next_line = None
-        while line is not None:
-            out_line = b''
-            # Remove any { } or [ ], and replace : with ,
-            for (non_string, string) in self.split_by_strings(line):
-                # Replace empty objects or arrays with ""
-                non_string = re.sub(rb'(\{(\s|\n)*\}|\[(\s|\n*)\])', lambda s: right_pad(len(s.group(0)), b'""'), non_string)
-                # Remove other braces entirely
-                non_string = re.sub(rb'([{}[\]])', lambda s: right_pad(len(s.group(0)), b' '), non_string)
-                # Replace : with ,
-                non_string = non_string.replace(b':', b',')
-                out_line += non_string
-                out_line += string
-
-            # Replace the first character with [
-            if next_line is None:
-                assert line[0] in [ord(x) for x in [ b'[', b'{', b' ', b'\t', b'\r', b'\n' ]]
-                out_line = b'[' + out_line[1:]
-
-            # Replace the last character with ]
-            next_line = next(lines, None)
-            if next_line is None:
-                assert out_line[-1] in [ord(x) for x in [ b']', b'}', b' ', b'\t', b'\r', b'\n' ]]
-                out_line = bytes(out_line[:-1] + b']')
-            line = next_line
-            out.write(out_line)
-
-    def split_by_strings(self, line: bytes):
-        result: list[tuple[bytes, bytes]] = []
-        while len(line) > 0:
-            quote = line.find(b'"')
-            if quote == -1:
-                result.append((line, b''))
-                break
-            end_quote = quote+1
-            while line[end_quote] != ord(b'"'):
-                assert end_quote < len(line)
-                if line[end_quote] == ord(b'\\'):
-                    end_quote += 1
-                end_quote += 1
-            result.append((line[:quote],line[quote:end_quote+1]))
-            line = line[end_quote+1:]
-        return result
-
-original_json_file = Path(sys.argv[1])
-for container_state in CONTAINER_STATES:
-    for scalar_state in SCALAR_STATES:
-        for string_state in STRING_STATES:
-            output_file = JsonFile(original_json_file, container_state, scalar_state, string_state)
-            if output_file.path.exists():
-                print(f"Skipping {output_file.path}")
-                continue
-            print(f"Writing {output_file.path}")
-            output_file.write()