Merge branch 'master' into parse_string_if_needed

* Add FracturedJson formatting support for DOM serialization

Implements FracturedJson formatting as requested in issue #2576.
FracturedJson produces human-readable yet compact JSON output by
intelligently choosing between different layout strategies based on
content complexity, length, and structure similarity.

Key features:
- Four layout modes: inline, compact multiline, table, and expanded
- Structure analysis pass to compute metrics before formatting
- Table formatting for arrays of similar objects with column alignment
- Configurable options for line length, indentation, padding, etc.

New files:
- fractured_json.h: Public API with fractured_json_options struct
- fractured_json-inl.h: Implementation (~1000 lines)
- json_structure_analyzer.h: Structure analysis for layout decisions
- fractured_formatter.h: Formatter class using CRTP pattern

Usage:
  dom::parser parser;
  element doc = parser.parse(json_string);
  std::cout << fractured_json(doc) << std::endl;

  // Or with custom options:
  fractured_json_options opts;
  opts.indent_spaces = 2;
  std::cout << fractured_json(doc, opts) << std::endl;

  // Or format any JSON string (useful with reflection API):
  auto formatted = fractured_json_string(minified_json);

Resolves #2576

* Add comprehensive tests for FracturedJson formatter

Adds 27 test cases covering all aspects of the FracturedJson formatter:

Core functionality tests (13):
- Roundtrip parsing verification
- Inline formatting for simple arrays and objects
- Expanded formatting for complex nested structures
- Compact multiline arrays with configurable items per line
- Table formatting for uniform arrays of objects
- Empty container handling
- All scalar types (string, int, uint, double, bool, null)
- String escaping (quotes, backslashes, control characters)
- Custom indentation options
- Deep nesting (10+ levels)
- Mixed type arrays

Edge case tests (11):
- Unicode strings (Chinese, emoji, Arabic, Russian, accented chars)
- Boundary numbers (INT64_MIN/MAX, UINT64_MAX, DBL_MIN/MAX)
- Nested arrays (arrays of arrays)
- Empty string values
- Keys with special characters (spaces, quotes, colons, etc.)
- Non-uniform arrays (should not trigger table mode)
- Very long strings (500+ chars)
- Large arrays (100 elements)
- Reflection API workflow simulation
- Control characters (tab, newline, CR, null)
- Single element containers

Option tests (3):
- Disable compact multiline mode
- Disable table format mode
- Disable all padding options

* Add FracturedJson integration with builder/reflection API

Extends FracturedJson to work seamlessly with the builder API, enabling
formatted output directly from C++ structs using static reflection.

New functions:
- to_fractured_json_string(obj, opts) - serialize struct to formatted JSON
- to_fractured_json(obj, output, opts) - same with output parameter
- extract_fractured_json<fields...>(obj, opts) - format only specific fields

These functions combine the builder's reflection-based serialization with
FracturedJson formatting in a single convenient call:

  struct User { int id; std::string name; bool active; };
  User user{1, "Alice", true};

  // Minified output (existing):
  auto minified = to_json_string(user);
  // {"id":1,"name":"Alice","active":true}

  // Formatted output (new):
  auto formatted = to_fractured_json_string(user);
  // { "id": 1, "name": "Alice", "active": true }

  // Partial extraction with formatting:
  auto partial = extract_fractured_json<"id", "name">(user);
  // { "id": 1, "name": "Alice" }

New files:
- generic/builder/fractured_json_builder.h - builder integration
- tests/builder/static_reflection_fractured_json_tests.cpp - 7 tests

* Fix INT64_MIN overflow and implement table_similarity_threshold

- Fix undefined behavior when negating INT64_MIN in estimate_number_length()
  and measure_value_length() by returning 20 (the exact length of the
  string representation) directly
- Actually use table_similarity_threshold in check_array_uniformity() by
  calling compute_object_similarity() to compare objects against the first
  object in the array

* Fix -Werror=effc++ member initialization warnings

Initialize all member variables in member initialization lists to
satisfy GCC's -Werror=effc++ flag:
- element_metrics::common_keys - add {} default initializer
- structure_analyzer - add default constructor with member init list
- fractured_formatter - add column_widths_{} to constructor
- fractured_string_builder - add analyzer_{} to constructor

* Add Rule of Five to structure_analyzer class

The class has a pointer member (current_opts_) which triggers
-Werror=effc++ requiring explicit copy/move operations. Delete
copy operations (class shouldn't be copied due to cache) and
default move operations.

* Fix Windows build: wrap std::max to avoid macro conflict

Windows.h defines max/min macros that interfere with std::max/std::min.
Wrapping in parentheses as (std::max)(...) prevents macro expansion.

* Fix GCC 15 false positive -Wfree-nonheap-object warning

GCC 15 on MINGW64 gives a false positive warning in parser_moving_parser()
when the std::vector<std::string> goes out of scope. Suppress this
specific warning with a pragma for GCC builds.

* Fix metrics cache key bug by passing metrics through recursion

The cache was using element addresses as keys, but dom::element objects
are lightweight wrappers that get copied during iteration, causing
different addresses between analysis and formatting phases. This resulted
in cache misses and fallback to empty metrics.

Solution: Store child metrics in the element_metrics struct and pass
them through recursive calls, eliminating the need for address-based
caching entirely.

Changes:
- Add children vector to element_metrics for hierarchical metrics
- Remove metrics_cache_ and related get_metrics/has_metrics methods
- Update all format functions to accept and pass child metrics
- Add public analyze_array/analyze_object overloads for standalone use

* Add ignore patterns for Node.js, Rust, and generated files

Add entries for node_modules, package-lock.json, Rust target
directories, local ablation artifacts, and generated documentation
files.

* Refactor: extract analyze_scalar helper to reduce code duplication

Extract common scalar type handling (STRING, INT64, UINT64, DOUBLE,
BOOL, NULL_VALUE) into a dedicated analyze_scalar method. Each scalar
type shares the same initialization pattern for complexity, child_count,
can_inline, and recommended_layout.

Also simplify boolean formatting in format_scalar to use ternary operator.

* Fix formatting and duplicate error message in amalgamate.py

Reformat cramped is_amalgamator condition to multi-line for readability.
Fix duplicate error message text in _included_filename_root and use
correct variable name (relative_root instead of root).

* Refactor: add count_newlines helper in fractured_json tests

Extract repeated newline counting loop into a reusable static helper
function, used by inline_array_test, inline_object_test, and
expanded_test.

* Revert "Add ignore patterns for Node.js, Rust, and generated files"

This reverts commit 4760ea7cd0.

* various minor changes

---------

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

.circleci/config.yml

@@ -1,316 +0,0 @@
-version: 2.1
-
-
-# We constantly run out of memory so please do not use parallelism (-j, -j4).
-
-# Reusable image / compiler definitions
-executors:
-  gcc8:
-    docker:
-      - image: conanio/gcc8
-        environment:
-          CXX: g++-8
-          CC: gcc-8
-          CMAKE_BUILD_FLAGS:
-          CTEST_FLAGS: --output-on-failure
-
-  gcc9:
-    docker:
-      - image: conanio/gcc9
-        environment:
-          CXX: g++-9
-          CC: gcc-9
-          CMAKE_BUILD_FLAGS:
-          CTEST_FLAGS: --output-on-failure
-
-  gcc10:
-    docker:
-      - image: conanio/gcc10
-        environment:
-          CXX: g++-10
-          CC: gcc-10
-          CMAKE_BUILD_FLAGS:
-          CTEST_FLAGS: --output-on-failure
-
-  clang10:
-    docker:
-      - image: conanio/clang10
-        environment:
-          CXX: clang++-10
-          CC: clang-10
-          CMAKE_BUILD_FLAGS:
-          CTEST_FLAGS: --output-on-failure
-
-  clang9:
-    docker:
-      - image: conanio/clang9
-        environment:
-          CXX: clang++-9
-          CC: clang-9
-          CMAKE_BUILD_FLAGS:
-          CTEST_FLAGS: --output-on-failure
-
-  clang6:
-    docker:
-      - image: conanio/clang60
-        environment:
-          CXX: clang++-6.0
-          CC: clang-6.0
-          CMAKE_BUILD_FLAGS:
-          CTEST_FLAGS: --output-on-failure
-
-# Reusable test commands (and initializer for clang 6)
-commands:
-  dependency_restore:
-    steps:
-      - restore_cache:
-          keys:
-            - cmake-cache-{{ checksum "dependencies/CMakeLists.txt" }}
-
-  dependency_cache:
-    steps:
-      - save_cache:
-          key: cmake-cache-{{ checksum "dependencies/CMakeLists.txt" }}
-          paths:
-            - dependencies/.cache
-
-  install_cmake:
-    steps:
-      - run: apt-get update -qq
-      - run: apt-get install -y cmake
-
-  cmake_prep:
-    steps:
-      - checkout
-      - run: mkdir -p build
-
-  cmake_build_cache:
-    steps:
-      - cmake_prep
-      - dependency_restore
-      - run: cmake  -DSIMDJSON_DEVELOPER_MODE=ON $CMAKE_FLAGS -DCMAKE_INSTALL_PREFIX:PATH=destination -B build .
-      - dependency_cache # dependencies are produced in the configure step
-
-  cmake_build:
-    steps:
-      - cmake_build_cache
-      - run: cmake  --build build
-
-  cmake_test:
-    steps:
-      - cmake_build
-      - run: |
-          cd build &&
-          tools/json2json -h &&
-          ctest $CTEST_FLAGS -L acceptance &&
-          ctest $CTEST_FLAGS -LE acceptance -LE explicitonly
-
-  cmake_assert_test:
-    steps:
-      - run: |
-          cd build &&
-          tools/json2json -h &&
-          ctest $CTEST_FLAGS -L assert
-
-  cmake_test_all:
-    steps:
-      - cmake_build
-      - run: |
-          cd build &&
-          tools/json2json -h &&
-          ctest $CTEST_FLAGS -DSIMDJSON_IMPLEMENTATION="haswell;westmere;fallback" -L acceptance -LE per_implementation &&
-          SIMDJSON_FORCE_IMPLEMENTATION=haswell ctest $CTEST_FLAGS -L per_implementation -LE explicitonly &&
-          SIMDJSON_FORCE_IMPLEMENTATION=westmere ctest $CTEST_FLAGS -L per_implementation -LE explicitonly &&
-          SIMDJSON_FORCE_IMPLEMENTATION=fallback ctest $CTEST_FLAGS -L per_implementation -LE explicitonly &&
-          ctest $CTEST_FLAGS -LE "acceptance|per_implementation" # Everything we haven't run yet, run now.
-
-
-  cmake_perftest:
-    steps:
-      - cmake_build_cache
-      - run: |
-          cmake -DSIMDJSON_ENABLE_DOM_CHECKPERF=ON --build  build --target checkperf &&
-          cd build &&
-          ctest --output-on-failure -R checkperf
-
-  # we not only want cmake to build and run tests, but we want also a successful installation from which we can build, link and run programs
-  cmake_install_test: # this version builds, install, test and then verify from the installation
-    steps:
-      - run: cd build && make install
-      - run: echo -e '#include <simdjson.h>\nint main(int argc,char**argv) {simdjson::dom::parser parser;simdjson::dom::element tweets = parser.load(argv[1]); }' > tmp.cpp && c++ -Ibuild/destination/include -Lbuild/destination/lib -std=c++17 -Wl,-rpath,build/destination/lib -o linkandrun tmp.cpp -lsimdjson && ./linkandrun jsonexamples/twitter.json
-
-  cmake_installed_test_cxx20: # assuming that it was installed, this tries to build using C++20
-    steps:
-      - run: echo -e '#include <simdjson.h>\nint main(int argc,char**argv) {simdjson::dom::parser parser;simdjson::dom::element tweets = parser.load(argv[1]); }' > tmp.cpp && c++ -Ibuild/destination/include -Lbuild/destination/lib -std=c++20 -Wl,-rpath,build/destination/lib -o linkandrun tmp.cpp -lsimdjson && ./linkandrun jsonexamples/twitter.json
-
-jobs:
-
-  # static
-  justlib-gcc10:
-    description: Build just the library, install it and do a basic test
-    executor: gcc10
-    environment: { CMAKE_FLAGS: -DSIMDJSON_JUST_LIBRARY=ON }
-    steps: [ cmake_build, cmake_install_test, cmake_installed_test_cxx20 ]
-  assert-gcc10:
-    description: Build the library with asserts on, install it and run tests
-    executor: gcc10
-    environment: { CMAKE_FLAGS: -DSIMDJSON_GOOGLE_BENCHMARKS=OFF -DCMAKE_CXX_FLAGS_RELEASE=-O3 }
-    steps: [ cmake_test, cmake_assert_test ]
-  assert-clang10:
-    description: Build just the library, install it and do a basic test
-    executor: clang10
-    environment: { CMAKE_FLAGS: -DSIMDJSON_GOOGLE_BENCHMARKS=OFF -DCMAKE_CXX_FLAGS_RELEASE=-O3 }
-    steps: [ cmake_test, cmake_assert_test ]
-  gcc10-perftest:
-    description: Build and run performance tests on GCC 10 and AVX 2 with a cmake static build, this test performance regression
-    executor: gcc10
-    environment: { CMAKE_FLAGS: -DSIMDJSON_GOOGLE_BENCHMARKS=OFF -DBUILD_SHARED_LIBS=OFF }
-    steps: [ cmake_perftest ]
-  gcc10:
-    description: Build and run tests on GCC 10 and AVX 2 with a cmake static build
-    executor: gcc10
-    environment: { CMAKE_FLAGS: -DSIMDJSON_GOOGLE_BENCHMARKS=ON -DBUILD_SHARED_LIBS=OFF }
-    steps: [ cmake_test, cmake_install_test, cmake_installed_test_cxx20 ]
-  clang6:
-    description: Build and run tests on clang 6 and AVX 2 with a cmake static build
-    executor: clang6
-    environment: { CMAKE_FLAGS: -DSIMDJSON_GOOGLE_BENCHMARKS=ON -DBUILD_SHARED_LIBS=OFF }
-    steps: [ cmake_test, cmake_install_test ]
-  clang10:
-    description: Build and run tests on clang 10 and AVX 2 with a cmake static build
-    executor: clang10
-    environment: { CMAKE_FLAGS: -DSIMDJSON_GOOGLE_BENCHMARKS=ON  -DBUILD_SHARED_LIBS=OFF }
-    steps: [ cmake_test, cmake_install_test, cmake_installed_test_cxx20 ]
-  # libcpp
-  libcpp-clang10:
-    description: Build and run tests on clang 10 and AVX 2 with a cmake static build and libc++
-    executor: clang10
-    environment: { CMAKE_FLAGS: -DSIMDJSON_USE_LIBCPP=ON  -DBUILD_SHARED_LIBS=OFF }
-    steps: [ cmake_test, cmake_install_test, cmake_installed_test_cxx20 ]
-  # sanitize
-  sanitize-gcc10:
-    description: Build and run tests on GCC 10 and AVX 2 with a cmake sanitize build
-    executor: gcc10
-    environment: { CMAKE_FLAGS: -DCMAKE_BUILD_TYPE=Debug -DBUILD_SHARED_LIBS=ON -DSIMDJSON_SANITIZE=ON, CTEST_FLAGS: --output-on-failure -LE explicitonly }
-    steps: [ cmake_test ]
-  sanitize-clang10:
-    description: Build and run tests on clang 10 and AVX 2 with a cmake sanitize build
-    executor: clang10
-    environment: { CMAKE_FLAGS: -DBUILD_SHARED_LIBS=ON -DSIMDJSON_NO_FORCE_INLINING=ON -DSIMDJSON_SANITIZE=ON, CTEST_FLAGS: --output-on-failure -LE explicitonly }
-    steps: [ cmake_test ]
-  threadsanitize-gcc10:
-    description: Build and run tests on GCC 10 and AVX 2 with a cmake sanitize build
-    executor: gcc10
-    environment: { CMAKE_FLAGS: -DBUILD_SHARED_LIBS=ON -DSIMDJSON_SANITIZE_THREADS=ON, CTEST_FLAGS: --output-on-failure -LE explicitonly }
-    steps: [ cmake_test ]
-  threadsanitize-clang10:
-    description: Build and run tests on clang 10 and AVX 2 with a cmake sanitize build
-    executor: clang10
-    environment: { CMAKE_FLAGS: -DBUILD_SHARED_LIBS=ON  -DSIMDJSON_NO_FORCE_INLINING=ON -DSIMDJSON_SANITIZE_THREADS=ON, CTEST_FLAGS: --output-on-failure -LE explicitonly }
-    steps: [ cmake_test ]
-  # dynamic
-  dynamic-gcc10:
-    description: Build and run tests on GCC 10 and AVX 2 with a cmake dynamic build
-    executor: gcc10
-    environment: { CMAKE_FLAGS: -DBUILD_SHARED_LIBS=ON }
-    steps: [ cmake_test, cmake_install_test ]
-  dynamic-clang10:
-    description: Build and run tests on clang 10 and AVX 2 with a cmake dynamic build
-    executor: clang10
-    environment: { CMAKE_FLAGS: -DBUILD_SHARED_LIBS=ON }
-    steps: [ cmake_test, cmake_install_test ]
-
-  # unthreaded
-  unthreaded-gcc10:
-    description: Build and run tests on GCC 10 and AVX 2 *without* threads
-    executor: gcc10
-    environment: { CMAKE_FLAGS: -DSIMDJSON_ENABLE_THREADS=OFF }
-    steps: [ cmake_test, cmake_install_test ]
-  unthreaded-clang10:
-    description: Build and run tests on Clang 10 and AVX 2 *without* threads
-    executor: clang10
-    environment: { CMAKE_FLAGS: -DSIMDJSON_ENABLE_THREADS=OFF }
-    steps: [ cmake_test, cmake_install_test ]
-
-  # noexcept
-  noexcept-gcc10:
-    description: Build and run tests on GCC 10 and AVX 2 with exceptions off
-    executor: gcc10
-    environment: { CMAKE_FLAGS: -DSIMDJSON_EXCEPTIONS=OFF }
-    steps: [ cmake_test, cmake_install_test ]
-  noexcept-clang10:
-    description: Build and run tests on Clang 10 and AVX 2 with exceptions off
-    executor: clang10
-    environment: { CMAKE_FLAGS: -DSIMDJSON_EXCEPTIONS=OFF }
-    steps: [ cmake_test, cmake_install_test ]
-
-  #
-  # Misc.
-  #
-
-  # make (test and checkperf)
-  arch-haswell-gcc10:
-    description: Build, run tests and check performance on GCC 10 with -march=haswell
-    executor: gcc10
-    environment: { CXXFLAGS: -march=haswell }
-    steps: [ cmake_test ]
-  arch-nehalem-gcc10:
-    description: Build, run tests and check performance on GCC 10 with -march=nehalem
-    executor: gcc10
-    environment: { CXXFLAGS: -march=nehalem }
-    steps: [ cmake_test ]
-  sanitize-haswell-gcc10:
-    description: Build and run tests on GCC 10 and AVX 2 with a cmake sanitize build
-    executor: gcc10
-    environment: {  CXXFLAGS: -march=haswell, CMAKE_FLAGS: -DCMAKE_BUILD_TYPE=Debug -DBUILD_SHARED_LIBS=ON -DSIMDJSON_SANITIZE=ON, CTEST_FLAGS: --output-on-failure -LE explicitonly }
-    steps: [ cmake_test ]
-  sanitize-haswell-clang10:
-    description: Build and run tests on clang 10 and AVX 2 with a cmake sanitize build
-    executor: clang10
-    environment: { CXXFLAGS: -march=haswell, CMAKE_FLAGS: -DBUILD_SHARED_LIBS=ON  -DSIMDJSON_NO_FORCE_INLINING=ON -DSIMDJSON_SANITIZE=ON, CTEST_FLAGS: --output-on-failure -LE explicitonly }
-    steps: [ cmake_test ]
-
-workflows:
-  version: 2.1
-  build_and_test:
-    jobs:
-      # full multi-implementation tests
-      #- gcc7 tested on GitHub actions
-      - gcc10 # do not delete this as it tests our performance
-      - clang6
-      #- clang10 # this gets tested a lot below
-
-      # libc++
-      - libcpp-clang10
-
-      # full single-implementation tests
-      - sanitize-gcc10
-      - sanitize-clang10
-      - threadsanitize-gcc10
-      - threadsanitize-clang10
-      - dynamic-gcc10
-      - dynamic-clang10
-      - unthreaded-gcc10
-      - unthreaded-clang10
-
-      # no exceptions
-      - noexcept-gcc10
-      - noexcept-clang10
-
-      # quicker make single-implementation tests
-      - arch-haswell-gcc10
-      - arch-nehalem-gcc10
-
-
-      # sanitized single-implementation tests
-      - sanitize-haswell-gcc10
-      - sanitize-haswell-clang10
-
-      # testing "just the library"
-      - justlib-gcc10
-
-      # testing asserts
-      - assert-gcc10
-      - assert-clang10
-
-      # TODO add windows: https://circleci.com/docs/2.0/configuration-reference/#windows

.github/ISSUE_TEMPLATE/bug_report.md

@@ -9,7 +9,8 @@ assignees: ''
 
 Before submitting an issue, please ensure that you have read the documentation:
 
-* Basics is an overview of how to use simdjson and its APIs: https://github.com/simdjson/simdjson/blob/master/doc/basics.md
+* Basics is an overview of how to use simdjson and its APIs to parse JSON: https://github.com/simdjson/simdjson/blob/master/doc/basics.md
+* Builder is an overview of how to use simdjson to generate JSON: https://github.com/simdjson/simdjson/blob/master/doc/builder.md
 * Performance shows some more advanced scenarios and how to tune for them: https://github.com/simdjson/simdjson/blob/master/doc/performance.md
 * Contributing: https://github.com/simdjson/simdjson/blob/master/CONTRIBUTING.md
 * We follow the [JSON specification as described by RFC 8259](https://www.rfc-editor.org/rfc/rfc8259.txt) (T. Bray, 2017). If you wish to support features that are not part of RFC 8259, then you should not refer to your issue as a bug.
@@ -37,7 +38,7 @@ If we cannot reproduce the issue, then we cannot address it. Note that a stack t
 
 It should be possible to trigger the bug by using solely simdjson with our default build setup. If you can only observe the bug within some specific context, with some other software, please reduce the issue first.
 
-**simjson release**
+**simdjson release**
 
 Unless you plan to contribute to simdjson, you should only work from releases. Please be mindful that our main branch may have additional features, bugs and documentation items.
 
@@ -55,6 +56,8 @@ We support up-to-date 64-bit ARM and x64 FreeBSD, macOS, Windows and Linux syste
 pre-release version of a compiler, do not report it as a bug to simdjson. However, we always
 invite contributions either in the form an analysis or of a code contribution.
 
+Under Windows, we support Visual Studio (both with LLVM and without). We do not support MinGW and other alternate compiler systems. Windows users should be aware that there [is a long-running bug with GCC under Windows](https://gcc.gnu.org/bugzilla/show_bug.cgi?id=54412).
+
 **Indicate whether you are willing or able to provide a bug fix as a pull request**
 
 If you plan to contribute to simdjson, please read our guide:

.github/ISSUE_TEMPLATE/feature_request.md

@@ -9,7 +9,8 @@ assignees: ''
 
 Before submitting an issue, please ensure that you have read the documentation:
 
-* Basics is an overview of how to use simdjson and its APIs: https://github.com/simdjson/simdjson/blob/master/doc/basics.md
+* Basics is an overview of how to use simdjson and its APIs to parse JSON: https://github.com/simdjson/simdjson/blob/master/doc/basics.md
+* Builder is an overview of how to use simdjson to generate JSON: https://github.com/simdjson/simdjson/blob/master/doc/builder.md
 * Performance shows some more advanced scenarios and how to tune for them: https://github.com/simdjson/simdjson/blob/master/doc/performance.md
 * Contributing: https://github.com/simdjson/simdjson/blob/master/CONTRIBUTING.md
 * We follow the [JSON specification as described by RFC 8259](https://www.rfc-editor.org/rfc/rfc8259.txt) (T. Bray, 2017).

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

@@ -9,7 +9,8 @@ assignees: ''
 
 Before submitting an issue, please ensure that you have read the documentation:
 
-* Basics is an overview of how to use simdjson and its APIs: https://github.com/simdjson/simdjson/blob/master/doc/basics.md
+* Basics is an overview of how to use simdjson and its APIs to parse JSON: https://github.com/simdjson/simdjson/blob/master/doc/basics.md
+* Builder is an overview of how to use simdjson to generate JSON: https://github.com/simdjson/simdjson/blob/master/doc/builder.md
 * Performance shows some more advanced scenarios and how to tune for them: https://github.com/simdjson/simdjson/blob/master/doc/performance.md
 * Contributing: https://github.com/simdjson/simdjson/blob/master/CONTRIBUTING.md
 * We follow the [JSON specification as described by RFC 8259](https://www.rfc-editor.org/rfc/rfc8259.txt) (T. Bray, 2017).

.github/pull_request_template.md

@@ -1,8 +1,54 @@
+Short title (summary):
+
+Description
+- What did you change and why? (1-3 sentences)
+- Issue reproduced / related issue: link the issue if relevant (e.g. #123)
+
+Type of change
+- [ ] Bug fix
+- [ ] Optimization
+- [ ] New feature
+- [ ] Refactor / cleanup
+- [ ] Documentation / tests
+- [ ] Other (please describe):
+
+How to verify / test
+- Add additional tests to verify bugs or new features.
+- If you claim performance gains, you should provide benchmark numbers using high quality benchmarking code.
 
 
-Our tests check whether you have introduced trailing white space. If such a test fails, please check the "artifacts button" above, which if you click it gives a link to a downloadable file to help you identify the issue. You can also run scripts/remove_trailing_whitespace.sh locally if you have a bash shell and the sed command available on your system.
+Please read before contributing:
+- CONTRIBUTING: https://github.com/simdjson/simdjson/blob/master/CONTRIBUTING.md
+- HACKING: https://github.com/simdjson/simdjson/blob/master/HACKING.md
 
-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
+If you can, we recommend running our tests with the sanitizers turned on.
+For non-Visual Studio users, it is as easy as doing:
+
+
+
+```bash
+cmake -B build -D SIMDJSON_SANITIZE=ON -D SIMDJSON_DEVELOPER_MODE=ON
+cmake --build build
+ctest --test-dir build
+```
+
+
+Our CI checks, among other things, for trailing whitespace. If a test fails for that reason,
+use the "artifacts" button to download the artifact and inspect the problematic lines,
+or run `scripts/remove_trailing_whitespace.sh` locally if you have a bash shell and `sed`.
+
+
+Checklist before submitting
+- [ ] I added/updated tests covering my change (if applicable)
+- [ ] Code builds locally and passes my check
+- [ ] Documentation / README updated if needed
+- [ ] Commits are atomic and messages are clear
+- [ ] I linked the related issue (if applicable)
+
+Final notes
+- For large PRs, prefer smaller incremental PRs or request staged review.
+
+Thanks for the contribution!
+

.github/workflows/aarch64.yml

@@ -1,4 +1,4 @@
-name: Ubuntu ppc64le (GCC 11)
+name: Ubuntu aarch64 (GCC 13)
 
 on:
   push:

.github/workflows/documentation.yml

@@ -2,7 +2,13 @@ name: Doxygen GitHub Pages
 
 on:
   release:
-    types: [created]
+    # Trigger when a release object is created and when it's published.
+    # Some GitHub flows create a release object then publish it later; include both.
+    types: [created, published]
+  # Also trigger on tag creation pushes so releasing via Git tags still runs the workflow
+  push:
+    tags:
+      - "v*"  # common release tag pattern like v1.2.3
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 
@@ -27,7 +33,7 @@ jobs:
       - name: Generate Doxygen Documentation
         run: doxygen
       - name: Deploy to GitHub Pages
-        uses: peaceiris/actions-gh-pages@v3
+        uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: doc/api/html

.github/workflows/rvv-1024-clang-18.yml

@@ -0,0 +1,29 @@
+name: Ubuntu rvv VLEN=1024 (clang 18)
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+      - master
+
+jobs:
+  build:
+    runs-on: ubuntu-24.04
+    steps:
+    - uses: actions/checkout@v4
+    - name: Install packages
+      run: |
+        sudo apt-get update -q -y
+        sudo apt-get install -y cmake make g++-riscv64-linux-gnu qemu-user-static clang-18
+    - name: Build
+      run: |
+        CXX=clang++-18 CXXFLAGS="--target=riscv64-linux-gnu -march=rv64gcv_zvbb" \
+        cmake --toolchain=cmake/toolchains-ci/riscv64-linux-gnu.cmake -DCMAKE_BUILD_TYPE=Release -B build
+        cmake --build build/ -j$(nproc)
+    - name: Test VLEN=1024
+      run: |
+        export QEMU_LD_PREFIX="/usr/riscv64-linux-gnu"
+        export QEMU_CPU="rv64,v=on,zvbb=on,vlen=1024,rvv_ta_all_1s=on,rvv_ma_all_1s=on"
+        ctest --timeout 1800 --output-on-failure --test-dir build -j $(nproc)

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

@@ -0,0 +1,29 @@
+name: Ubuntu rvv VLEN=128 (clang 17)
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+      - master
+
+jobs:
+  build:
+    runs-on: ubuntu-24.04
+    steps:
+    - uses: actions/checkout@v4
+    - name: Install packages
+      run: |
+        sudo apt-get update -q -y
+        sudo apt-get install -y cmake make g++-riscv64-linux-gnu qemu-user-static clang-17
+    - name: Build
+      run: |
+        CXX=clang++-17 CXXFLAGS="--target=riscv64-linux-gnu -march=rv64gcv" \
+        cmake --toolchain=cmake/toolchains-ci/riscv64-linux-gnu.cmake -DCMAKE_BUILD_TYPE=Release -B build
+        cmake --build build/ -j$(nproc)
+    - name: Test VLEN=128
+      run: |
+        export QEMU_LD_PREFIX="/usr/riscv64-linux-gnu"
+        export QEMU_CPU="rv64,v=on,vlen=128,rvv_ta_all_1s=on,rvv_ma_all_1s=on"
+        ctest --timeout 1800 --output-on-failure --test-dir build -j $(nproc)

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

@@ -0,0 +1,29 @@
+name: Ubuntu rvv VLEN=256 (gcc 14)
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+      - master
+
+jobs:
+  build:
+    runs-on: ubuntu-24.04
+    steps:
+    - uses: actions/checkout@v4
+    - name: Install packages
+      run: |
+        sudo apt-get update -q -y
+        sudo apt-get install -y cmake make g++-14-riscv64-linux-gnu qemu-user-static
+    - name: Build
+      run: |
+        CXX=riscv64-linux-gnu-g++-14 CXXFLAGS=-march=rv64gcv \
+        cmake --toolchain=cmake/toolchains-ci/riscv64-linux-gnu.cmake -DCMAKE_BUILD_TYPE=Release -B build
+        cmake --build build/ -j$(nproc)
+    - name: Test VLEN=256
+      run: |
+        export QEMU_LD_PREFIX="/usr/riscv64-linux-gnu"
+        export QEMU_CPU="rv64,v=on,zvbb=on,vlen=256,rvv_ta_all_1s=on,rvv_ma_all_1s=on"
+        ctest --timeout 1800 --output-on-failure --test-dir build -j $(nproc)

.github/workflows/ubuntu22-cxx20.yml

@@ -14,20 +14,52 @@ jobs:
         with:
           path: dependencies/.cache
           key: ${{ hashFiles('dependencies/CMakeLists.txt') }}
-      - name: Use cmake
+
+      - name: Configure Debug Build
         run: |
-          mkdir builddebug &&
+          CXX=g++-12 cmake -DSIMDJSON_CXX_STANDARD=20 -DCMAKE_BUILD_TYPE=Debug -DSIMDJSON_GOOGLE_BENCHMARKS=OFF -DSIMDJSON_DEVELOPER_MODE=ON -DBUILD_SHARED_LIBS=OFF -B builddebug
-          cd builddebug &&
+
-          CXX=g++-12 cmake -DSIMDJSON_CXX_STANDARD=20 -DCMAKE_BUILD_TYPE=Debug -DSIMDJSON_GOOGLE_BENCHMARKS=OFF -DSIMDJSON_DEVELOPER_MODE=ON -DBUILD_SHARED_LIBS=OFF ..  &&
+      - name: Compile Debug Build
-          cmake --build .   &&
+        run: |
-          ctest --output-on-failure -LE explicitonly -j   &&
+          cmake --build builddebug
-          cd .. &&
+
-          mkdir build &&
+      - name: Test Debug Build
-          cd build &&
+        run: |
-          CXX=g++-12 cmake -DSIMDJSON_CXX_STANDARD=20  -DSIMDJSON_GOOGLE_BENCHMARKS=ON -DSIMDJSON_DEVELOPER_MODE=ON -DBUILD_SHARED_LIBS=OFF -DCMAKE_INSTALL_PREFIX:PATH=destination ..  &&
+          ctest --output-on-failure -LE explicitonly -j --test-dir builddebug
-          cmake --build .   &&
+
-          ctest --output-on-failure -LE explicitonly -j   &&
+      - name: Configure Release Build
-          cmake --install . &&
+        run: |
-          echo -e '#include <simdjson.h>\nint main(int argc,char**argv) {simdjson::dom::parser parser;simdjson::dom::element tweets = parser.load(argv[1]); }' > tmp.cpp && c++ -Idestination/include -Ldestination/lib -std=c++17 -Wl,-rpath,destination/lib -o linkandrun tmp.cpp -lsimdjson && ./linkandrun jsonexamples/twitter.json &&
+          CXX=g++-12 cmake -DSIMDJSON_CXX_STANDARD=20 -DSIMDJSON_GOOGLE_BENCHMARKS=ON -DSIMDJSON_DEVELOPER_MODE=ON -DBUILD_SHARED_LIBS=OFF -DCMAKE_INSTALL_PREFIX:PATH=destination -B build
-          cd ../tests/installation_tests/find &&
+
-          mkdir build && cd build && cmake -DCMAKE_INSTALL_PREFIX:PATH=../../../build/destination .. &&  cmake --build .
+      - name: Compile Release Build
+        run: |
+          cmake --build build
+
+      - name: Test Release Build
+        run: |
+          ctest --output-on-failure -LE explicitonly -j --test-dir build
+
+      - name: Install Release Build
+        run: |
+          cmake --install build
+
+      - name: Generate Example Code
+        run: |
+          echo -e '#include <simdjson.h>\nint main(int argc,char**argv) {simdjson::dom::parser parser;simdjson::dom::element tweets = parser.load(argv[1]); }' > tmp.cpp
+
+      - name: Compile Example Code
+        run: |
+          c++ -Idestination/include -Ldestination/lib -std=c++17 -Wl,-rpath,destination/lib -o linkandrun tmp.cpp -lsimdjson
+
+      - name: Run Example Code
+        run: |
+          ./linkandrun jsonexamples/twitter.json
+
+      - name: Configure Find Tests
+        run: |
+          cd tests/installation_tests/find && \
+          cmake -DCMAKE_INSTALL_PREFIX:PATH=../../../destination -B build
+
+      - name: Compile Find Tests
+        run: |
+          cd tests/installation_tests/find && cmake --build build

.github/workflows/ubuntu24-cxx20-noexcept.yml

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

.github/workflows/ubuntu24-noexcept.yml

@@ -31,4 +31,4 @@ 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 &&
           mkdir testfindpackage &&
           cd testfindpackage &&
-          echo -e 'cmake_minimum_required(VERSION 3.1)\nproject(simdjsontester)\nset(CMAKE_CXX_STANDARD 17)\nfind_package(simdjson REQUIRED)'> CMakeLists.txt && mkdir build && cd build && cmake -DCMAKE_INSTALL_PREFIX:PATH=../destination .. &&  cmake --build .
+          echo -e 'cmake_minimum_required(VERSION 3.14)\nproject(simdjsontester)\nset(CMAKE_CXX_STANDARD 17)\nfind_package(simdjson REQUIRED)'> CMakeLists.txt && mkdir build && cd build && cmake -DCMAKE_INSTALL_PREFIX:PATH=../destination .. &&  cmake --build .

.github/workflows/ubuntu24-nothread.yml

@@ -31,4 +31,4 @@ 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 &&
           mkdir testfindpackage &&
           cd testfindpackage &&
-          echo -e 'cmake_minimum_required(VERSION 3.1)\nproject(simdjsontester)\nset(CMAKE_CXX_STANDARD 17)\nfind_package(simdjson REQUIRED)'> CMakeLists.txt && mkdir build && cd build && cmake -DCMAKE_INSTALL_PREFIX:PATH=../destination .. &&  cmake --build .
+          echo -e 'cmake_minimum_required(VERSION 3.14)\nproject(simdjsontester)\nset(CMAKE_CXX_STANDARD 17)\nfind_package(simdjson REQUIRED)'> CMakeLists.txt && mkdir build && cd build && cmake -DCMAKE_INSTALL_PREFIX:PATH=../destination .. &&  cmake --build .

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

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

.vscode/settings.json

@@ -3,6 +3,9 @@
         {"column": 95 },
         {"column": 120 }
     ],
+    "cmake.configureArgs": [
+        "-DSIMDJSON_DEVELOPER_MODE=ON"
+    ],
     "files.trimTrailingWhitespace": true,
     "files.associations": {
         ".clangd": "yaml",

CMakeLists.txt

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

Doxyfile

@@ -38,7 +38,7 @@ PROJECT_NAME           = simdjson
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = "4.0.0"
+PROJECT_NUMBER         = "4.2.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

HACKING.md

@@ -20,13 +20,54 @@ If you plan to contribute to simdjson, please read our [CONTRIBUTING](https://gi
 Build Quickstart
 ------------------------------
 
+For non-Windows system,
+
 ```bash
-mkdir build
+cmake -B -D SIMDJSON_DEVELOPER_MODE=ON ..
-cd build
+cmake --build build
-cmake -D SIMDJSON_DEVELOPER_MODE=ON ..
+ctest --test-dir build
-cmake --build .
 ```
 
+It is similar for Visual Studio users, please see the CMake or Visual Studio documentation.
+
+By default the library is built in Release mode.
+
+
+Assertions and development checks
+------------------------------
+
+We do not use conventional `assert` in simdjson. Instead we use the macro
+`SIMDJSON_ASSUME`:
+
+```cpp
+SIMDJSON_ASSUME(something_that_is_true());
+```
+
+Sometimes, you need to do a bit more work that a simple check.
+The `SIMDJSON_DEVELOPMENT_CHECKS` macro is true only in Debug mode unless manually set.
+It is acceptable to add checks that you would not do in Release mode as long as
+they are guarded:
+
+```cpp
+#if SIMDJSON_DEVELOPMENT_CHECKS
+// do sanity checks here
+```
+
+
+Working with sanitizers
+------------------------------
+
+The simdjson library must be memory-safe. We cannot allow buffer overruns.
+During development, if you system supports it, we recommend configuring
+the project with `-D SIMDJSON_SANITIZE=ON`.
+
+```bash
+cmake -B -D SIMDJSON_SANITIZE=ON -D SIMDJSON_DEVELOPER_MODE=ON ..
+cmake --build build
+ctest --test-dir build
+```
+
+
 Design notes
 ------------------------------
 
@@ -69,6 +110,24 @@ workflows used by simdjson.
 Directory Structure and Source
 ------------------------------
 
+Before diving into the directory structure, here are key concepts used in the codebase:
+
+- **Amalgamated File**: A file that is conditionally included in the amalgamation process. These are wrapped in `#ifndef SIMDJSON_CONDITIONAL_INCLUDE` blocks and are included based on the target implementation (e.g., ARM64, x86). They include implementation-specific files (e.g., `arm64.h`) and generic files (e.g., under `generic/`). Amalgamated files have associated dependency files (`dependencies.h`) to track includes.
+
+- **Amalgamator File**: A file that orchestrates the inclusion of amalgamated files. Examples: `arm64.h`, `arm64/implementation.h`, `generic/amalgamated.h`. These are not themselves amalgamated but control conditional inclusions.
+
+- **Free Dependency File**: A top-level header that is always included unconditionally. These do not have dependency files and represent the public API (e.g., main headers).
+
+- **Implementation-Specific File**: A file tied to a specific CPU architecture or instruction set (e.g., `arm64/`, `haswell/`). These must be amalgamated.
+
+- **Generic File**: A shared file (under `generic/` or `simdjson/generic/`) that contains common code included once per implementation.
+
+- **Builtin File**: Special files under `simdjson/builtin/` that handle the builtin implementation, a fallback/default implementation used when no optimized implementation is available.
+
+- **Conditional Include Block**: A section wrapped in `#ifndef SIMDJSON_CONDITIONAL_INCLUDE` for editor-only or implementation-specific content.
+
+The script `singleheader/amalgation_helper.py` will generate an HTML report which you can use to visualize the status of each file.
+
 simdjson's source structure, from the top level, looks like this:
 
 * **CMakeLists.txt:** The main build system.
@@ -92,6 +151,12 @@ simdjson's source structure, from the top level, looks like this:
     * simdjson/generic/ondemand/*.h: individual On-Demand classes, generically written.
       * simdjson/generic/ondemand/dependencies.h: dependencies on common, non-implementation-specific simdjson classes. This will be included before including amalgamated.h.
       * simdjson/generic/ondemand/amalgamated.h: all generic ondemand classes for an implementation.
+  * simdjson/builder.h: the `simdjson::builder` namespace. Includes all public builder classes.
+    * simdjson/builtin/builder.h: the `simdjson::builtin::builder` namespace.
+    * simdjson/arm64|fallback|haswell|icelake|ppc64|westmere/builder.h: the `simdjson::<implementation>::builder` namespace. Builder compiled for the specific implementation.
+    * simdjson/generic/builder/*.h: individual Builder classes, generically written.
+      * simdjson/generic/builder/dependencies.h: dependencies on common, non-implementation-specific simdjson classes. This will be included before including amalgamated.h.
+      * simdjson/generic/builder/amalgamated.h: all generic builder classes for an implementation.
 * **src:** The source files for non-inlined functionality (e.g. the architecture-specific parser
   implementations).
   * simdjson.cpp: A "main source" that includes all implementation files from src/. This is
@@ -103,12 +168,10 @@ simdjson's source structure, from the top level, looks like this:
     * generic/stage2/*.h: `simdjson::<implementation>::stage2` namespace. Generic implementation of the tape creator, which consumes the index from stage 1 and actually parses numbers and string and such. Used for the DOM interface.
 
 Other important files and directories:
-* **.drone.yml:** Definitions for Drone CI.
-* **.appveyor.yml:** Definitions for Appveyor CI (Windows).
-* **.circleci:** Definitions for Circle CI.
 * **.github/workflows:** Definitions for GitHub Actions (CI).
 * **singleheader:** Contains generated `simdjson.h` and `simdjson.cpp` that we release. The files `singleheader/simdjson.h` and `singleheader/simdjson.cpp` should never be edited by hand.
-* **singleheader/amalgamate.py:** Generates `singleheader/simdjson.h` and `singleheader/simdjson.cpp` for release (python script).
+* **singleheader/amalgamate.py:** Generates `singleheader/simdjson.h` and `singleheader/simdjson.cpp` for release (python script). If you add a new implementation (e.g., rvv), you need to edit this file (IMPLEMENTATIONS).
+* **singleheader/amalgation_helper.py:** Generates and `amalgamation_report.html` that helps you understand the status of each file.
 * **benchmark:** This is where we do benchmarking. Benchmarking is core to every change we make; the
   cardinal rule is don't regress performance without knowing exactly why, and what you're trading
   for it. Many of our benchmarks are microbenchmarks. We are effectively doing controlled scientific experiments for the purpose of understanding what affects our performance. So we simplify as much as possible. We try to avoid irrelevant factors such as page faults, interrupts, unnecessary system calls. We recommend checking the performance as follows:

README.md

@@ -1,5 +1,3 @@
-
-[![Fuzzing Status](https://oss-fuzz-build-logs.storage.googleapis.com/badges/simdjson.svg)](https://bugs.chromium.org/p/oss-fuzz/issues/list?sort=-opened&can=1&q=proj:simdjson)
 [![][license img]][license] [![][licensemit img]][licensemit]
 
 
@@ -8,7 +6,8 @@
 simdjson : Parsing gigabytes of JSON per second
 ===============================================
 
-<img src="images/logo.png" width="10%" style="float: right">
+<img src="images/official_logo/logo_noir/SVG/logo_simdjson_noir.svg" width="40%" style="float: right">
+
 JSON is everywhere on the Internet. Servers spend a *lot* of time parsing it. We need a fresh
 approach. The simdjson library uses commonly available SIMD instructions and microparallel algorithms
 to parse JSON 4x  faster than RapidJSON and 25x faster than JSON for Modern C++.
@@ -64,10 +63,14 @@ Real-world usage
 - [WasmEdge](https://wasmedge.org)
 - [RonDB](https://github.com/logicalclocks/rondb)
 - [GreptimeDB](https://github.com/GreptimeTeam/greptimedb)
+- [mamba](https://github.com/mamba-org/mamba)
 
 
 If you are planning to use simdjson in a product, please work from one of our releases.
 
+
+
+
 Quick Start
 -----------
 
@@ -84,7 +87,7 @@ The simdjson library is easily consumable with a single .h and .cpp file.
    ```
 2. Create `quickstart.cpp`:
 
-```c++
+```cpp
 #include <iostream>
 #include "simdjson.h"
 using namespace simdjson;
@@ -114,11 +117,14 @@ Usage documentation is available:
 * [Implementation Selection](doc/implementation-selection.md) describes runtime CPU detection and
   how you can work with it.
 * [API](https://simdjson.github.io/simdjson/) contains the automatically generated API documentation.
+* [Compile-Time Parsing](doc/compile_time.md) presents our compile-time parsing function (C++26 only).
+
 
 Godbolt
 -------------
 
 Some users may want to browse code along with the compiled assembly. You want to check out the following lists of examples:
+* [C++26 reflection example](https://godbolt.org/z/K3Px64TqK)
 * [simdjson examples with errors handled through exceptions](https://godbolt.org/z/7G5qE4sr9)
 * [simdjson examples with errors without exceptions](https://godbolt.org/z/e9dWb9E4v)
 
@@ -207,6 +213,21 @@ For the video inclined, <br />
 [![simdjson at QCon San Francisco 2019](http://img.youtube.com/vi/wlvKAT7SZIQ/0.jpg)](http://www.youtube.com/watch?v=wlvKAT7SZIQ)<br />
 (It was the best voted talk, we're kinda proud of it.)
 
+Citing this work
+-----------------
+
+If you use simdjson in published research, please cite the software library. A suitable BibTeX entry is:
+
+```bibtex
+@misc{simdjson,
+  title={{The simdjson library: Parsing Gigabytes of JSON per Second}},
+  author={Daniel Lemire and Geoff Langdale and John Keiser and Paul Dreik and Francisco Thiesen and others},
+  year={2019},
+  howpublished={Software library},
+  note={https://github.com/simdjson/simdjson}
+}
+```
+
 Funding
 -------
 
@@ -227,6 +248,13 @@ Contributing to simdjson
 Head over to [CONTRIBUTING.md](CONTRIBUTING.md) for information on contributing to simdjson, and
 [HACKING.md](HACKING.md) for information on source, building, and architecture/design.
 
+
+Stars
+------
+
+[![Star History Chart](https://api.star-history.com/svg?repos=simdjson/simdjson&type=Date)](https://www.star-history.com/#simdjson/simdjson&Date)
+
+
 License
 -------
 

benchmark/CMakeLists.txt

@@ -35,6 +35,16 @@ if (TARGET benchmark::benchmark)
   endif()
 endif()
 
+
+include(CheckCXXCompilerFlag)
+check_cxx_compiler_flag("-std=c++20" SIMDJSON_COMPILER_SUPPORTS_CXX20)
 if(SIMDJSON_STATIC_REFLECTION)
   add_subdirectory(static_reflect)
-endif(SIMDJSON_STATIC_REFLECTION)
+else()
+  if(SIMDJSON_EXCEPTIONS AND SIMDJSON_COMPILER_SUPPORTS_CXX20)
+    add_subdirectory(from)
+    add_subdirectory(car_builder)
+  endif()
+endif(SIMDJSON_STATIC_REFLECTION)
+
+

benchmark/accessor_performance/README.md

@@ -0,0 +1,46 @@
+# Accessor Performance Benchmarks (C++26)
+
+These benchmarks compare the performance of runtime vs compile-time JSON accessors.
+For the comparison to be meaningful, you must build simdjson with support for
+C++26 reflexion. See the `p2996` repository in the main project directory.
+
+## Files
+
+- `accessor_benchmark.h` - Common benchmark framework and test data
+- `runtime_accessors.h` - Runtime `at_path()` benchmarks
+- `compile_time_accessors.h` - Compile-time `at_path_compiled()` benchmarks (requires C++26 reflection)
+
+## Benchmarks
+
+Each benchmark measures parsing + single field access:
+
+1. **accessor_simple** - Simple field: `.name`
+2. **accessor_nested** - Nested field: `.address.city`
+3. **accessor_deep** - Deep nested field: `.address.coordinates.lat`
+
+## Building (Linux/macOS)
+
+```bash
+cmake -B build -D SIMDJSON_STATIC_REFLECTION=ON -DSIMDJSON_DEVELOPER_MODE=ON
+cmake --build build --target=bench_ondemand
+```
+
+The `SIMDJSON_STATIC_REFLECTION` will be made unnecessary once mainstream compilers
+begin supporting C++26 sufficiently well.
+
+## Running (Linux/macOS)
+
+
+```bash
+# Run all accessor benchmarks
+./build/bench_ondemand --benchmark_filter="accessor"
+```
+
+## Results
+
+We find that compile-time accessors show performance improvements that scale with path depth:
+- Simple fields: ~1.2x faster
+- Nested fields: ~1.5x faster
+- Deep nested fields: ~1.8x faster
+
+The speedup comes from eliminating runtime path parsing and conversion overhead.

benchmark/accessor_performance/accessor_benchmark.h

@@ -0,0 +1,132 @@
+#pragma once
+
+#include "json_benchmark/file_runner.h"
+#include <string>
+
+namespace accessor_performance {
+
+using namespace json_benchmark;
+
+// Test JSON for accessor benchmarks
+static const char* TEST_JSON = R"({
+  "name": "Alice",
+  "age": 30,
+  "email": "alice@example.com",
+  "address": {
+    "street": "123 Main St",
+    "city": "Boston",
+    "state": "MA",
+    "zip": 12345,
+    "coordinates": {
+      "lat": 42.3601,
+      "lon": -71.0589
+    }
+  },
+  "scores": [95, 87, 92, 88, 91],
+  "preferences": {
+    "theme": "dark",
+    "notifications": {
+      "email": true,
+      "push": false,
+      "sms": true
+    }
+  }
+})";
+
+// Struct definitions for compile-time validation
+#if SIMDJSON_STATIC_REFLECTION
+struct Coordinates {
+  double lat;
+  double lon;
+};
+
+struct Address {
+  std::string street;
+  std::string city;
+  std::string state;
+  int64_t zip;
+  Coordinates coordinates;
+};
+
+struct Notifications {
+  bool email;
+  bool push;
+  bool sms;
+};
+
+struct Preferences {
+  std::string theme;
+  Notifications notifications;
+};
+
+struct TestData {
+  std::string name;
+  int64_t age;
+  std::string email;
+  Address address;
+  std::vector<int64_t> scores;
+  Preferences preferences;
+};
+#endif // SIMDJSON_STATIC_REFLECTION
+
+// Single-access benchmark runner: measures ONE field access per iteration
+template<typename I>
+struct single_access_runner : public file_runner<I> {
+  std::string result_string;
+  int64_t result_int{};
+  double result_double{};
+  bool result_bool{};
+
+  bool setup(benchmark::State &state) {
+    this->json = simdjson::padded_string(TEST_JSON, strlen(TEST_JSON));
+    state.SetBytesProcessed(int64_t(state.iterations()) * int64_t(this->json.size()));
+    return true;
+  }
+
+  bool before_run(benchmark::State &state) {
+    if (!file_runner<I>::before_run(state)) { return false; }
+    result_string.clear();
+    result_int = 0;
+    result_double = 0.0;
+    result_bool = false;
+    return true;
+  }
+
+  bool run(benchmark::State &) {
+    return this->implementation.run(this->json, result_string, result_int, result_double, result_bool);
+  }
+
+  template<typename R>
+  bool diff(benchmark::State &state, single_access_runner<R> &reference) {
+    if (result_string != reference.result_string ||
+        result_int != reference.result_int ||
+        result_double != reference.result_double ||
+        result_bool != reference.result_bool) {
+      std::cerr << "Accessor benchmark results differ!" << std::endl;
+      return false;
+    }
+    return true;
+  }
+
+  size_t items_per_iteration() {
+    return 1;
+  }
+};
+
+// Benchmark template definitions
+struct runtime_at_path_simple;
+template<typename I> simdjson_inline static void accessor_simple(benchmark::State &state) {
+  run_json_benchmark<single_access_runner<I>, single_access_runner<runtime_at_path_simple>>(state);
+}
+
+struct runtime_at_path_nested;
+template<typename I> simdjson_inline static void accessor_nested(benchmark::State &state) {
+  run_json_benchmark<single_access_runner<I>, single_access_runner<runtime_at_path_nested>>(state);
+}
+
+struct runtime_at_path_deep;
+template<typename I> simdjson_inline static void accessor_deep(benchmark::State &state) {
+  run_json_benchmark<single_access_runner<I>, single_access_runner<runtime_at_path_deep>>(state);
+}
+
+} // namespace accessor_performance

benchmark/accessor_performance/compile_time_accessors.h

@@ -0,0 +1,56 @@
+#pragma once
+
+#if SIMDJSON_EXCEPTIONS && SIMDJSON_STATIC_REFLECTION
+
+#include "accessor_benchmark.h"
+
+namespace accessor_performance {
+
+using namespace simdjson;
+
+struct compile_time_at_path_simple {
+  ondemand::parser parser{};
+
+  bool run(simdjson::padded_string &json, std::string &result_str, int64_t&, double&, bool&) {
+    auto doc = parser.iterate(json);
+    std::string_view name;
+    auto r = ondemand::json_path::at_path_compiled<TestData, ".name">(doc);
+    if (r.get(name) != SUCCESS) return false;
+    result_str = name;
+    return true;
+  }
+};
+
+struct compile_time_at_path_nested {
+  ondemand::parser parser{};
+
+  bool run(simdjson::padded_string &json, std::string &result_str, int64_t&, double&, bool&) {
+    auto doc = parser.iterate(json);
+    std::string_view city;
+    auto r = ondemand::json_path::at_path_compiled<TestData, ".address.city">(doc);
+    if (r.get(city) != SUCCESS) return false;
+    result_str = city;
+    return true;
+  }
+};
+
+struct compile_time_at_path_deep {
+  ondemand::parser parser{};
+
+  bool run(simdjson::padded_string &json, std::string&, int64_t&, double &result_dbl, bool&) {
+    auto doc = parser.iterate(json);
+    double lat;
+    auto r = ondemand::json_path::at_path_compiled<TestData, ".address.coordinates.lat">(doc);
+    if (r.get(lat) != SUCCESS) return false;
+    result_dbl = lat;
+    return true;
+  }
+};
+
+BENCHMARK_TEMPLATE(accessor_simple, compile_time_at_path_simple)->UseManualTime();
+BENCHMARK_TEMPLATE(accessor_nested, compile_time_at_path_nested)->UseManualTime();
+BENCHMARK_TEMPLATE(accessor_deep, compile_time_at_path_deep)->UseManualTime();
+
+} // namespace accessor_performance
+
+#endif // SIMDJSON_EXCEPTIONS && SIMDJSON_STATIC_REFLECTION

benchmark/accessor_performance/runtime_accessors.h

@@ -0,0 +1,53 @@
+#pragma once
+
+#if SIMDJSON_EXCEPTIONS
+
+#include "accessor_benchmark.h"
+
+namespace accessor_performance {
+
+using namespace simdjson;
+
+struct runtime_at_path_simple {
+  ondemand::parser parser{};
+
+  bool run(simdjson::padded_string &json, std::string &result_str, int64_t&, double&, bool&) {
+    auto doc = parser.iterate(json);
+    std::string_view name;
+    if (doc.at_path(".name").get(name) != SUCCESS) return false;
+    result_str = name;
+    return true;
+  }
+};
+
+struct runtime_at_path_nested {
+  ondemand::parser parser{};
+
+  bool run(simdjson::padded_string &json, std::string &result_str, int64_t&, double&, bool&) {
+    auto doc = parser.iterate(json);
+    std::string_view city;
+    if (doc.at_path(".address.city").get(city) != SUCCESS) return false;
+    result_str = city;
+    return true;
+  }
+};
+
+struct runtime_at_path_deep {
+  ondemand::parser parser{};
+
+  bool run(simdjson::padded_string &json, std::string&, int64_t&, double &result_dbl, bool&) {
+    auto doc = parser.iterate(json);
+    double lat;
+    if (doc.at_path(".address.coordinates.lat").get(lat) != SUCCESS) return false;
+    result_dbl = lat;
+    return true;
+  }
+};
+
+BENCHMARK_TEMPLATE(accessor_simple, runtime_at_path_simple)->UseManualTime();
+BENCHMARK_TEMPLATE(accessor_nested, runtime_at_path_nested)->UseManualTime();
+BENCHMARK_TEMPLATE(accessor_deep, runtime_at_path_deep)->UseManualTime();
+
+} // namespace accessor_performance
+
+#endif // SIMDJSON_EXCEPTIONS

benchmark/apple/apple_arm_events.h

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

benchmark/bench_ondemand.cpp

@@ -148,4 +148,9 @@ SIMDJSON_POP_DISABLE_WARNINGS
 #include "large_amazon_cellphones/simdjson_dom.h"
 #include "large_amazon_cellphones/simdjson_ondemand.h"
 
+#include "accessor_performance/runtime_accessors.h"
+#if SIMDJSON_STATIC_REFLECTION
+#include "accessor_performance/compile_time_accessors.h"
+#endif
+
 BENCHMARK_MAIN();

benchmark/car_builder/CMakeLists.txt

@@ -0,0 +1,14 @@
+# Executable
+add_executable(benchmark_car_builder benchmark_car_builder.cpp)
+
+# Compile for C++20.
+target_compile_features(benchmark_car_builder PRIVATE cxx_std_20)
+
+# Check if -march=native is supported
+include(CheckCXXCompilerFlag)
+check_cxx_compiler_flag("-march=native" SIMDJSON_SUPPORTS_MARCH_NATIVE)
+if(SIMDJSON_SUPPORTS_MARCH_NATIVE)
+  target_compile_options(benchmark_car_builder PRIVATE -march=native)
+endif()
+
+target_include_directories(benchmark_car_builder PRIVATE ${CMAKE_CURRENT_LIST_DIR}/..)

benchmark/car_builder/benchmark_car_builder.cpp

@@ -0,0 +1,127 @@
+#include "event_counter.h"
+#include <random>
+#include <vector>
+
+#include <simdjson.h>
+
+event_collector collector;
+
+struct Car {
+  std::string make;
+  std::string model;
+  int64_t year; // We deliberately do not include the tire pressure.
+};
+
+std::vector<Car> generate_random_cars(size_t count) {
+  static const std::vector<std::string> makes = {"Toyota", "Honda", "Ford",
+                                                 "BMW", "Mazda"};
+  static const std::vector<std::string> models = {"Camry", "Civic", "Focus",
+                                                  "320i", "3"};
+  static thread_local std::mt19937 rng{std::random_device{}()};
+  std::uniform_int_distribution<int> make_dist(0, makes.size() - 1);
+  std::uniform_int_distribution<int> model_dist(0, models.size() - 1);
+  std::uniform_int_distribution<int64_t> year_dist(2000, 2025);
+  std::uniform_real_distribution<double> pressure_dist(30.0, 45.0);
+
+  std::vector<Car> cars;
+  cars.reserve(count);
+  for (size_t i = 0; i < count; ++i) {
+    Car car;
+    car.make = makes[make_dist(rng)];
+    car.model = models[model_dist(rng)];
+    car.year = year_dist(rng);
+    cars.push_back(std::move(car));
+  }
+  return cars;
+}
+
+std::string_view serialize(simdjson::builder::string_builder &sb,
+                           const std::vector<Car> &cars) {
+  sb.clear();
+  sb.start_array();
+  for (const auto &car : cars) {
+    sb.start_object();
+    sb.append_key_value("make", car.make);
+    sb.append_comma();
+    sb.append_key_value("model", car.model);
+    sb.append_comma();
+    sb.append_key_value("year", car.year);
+    sb.end_object();
+  }
+  sb.end_array();
+  std::string_view result;
+  if (sb.view().get(result)) {
+    return ""; // unexpected (error)
+  }
+  return result;
+}
+
+double pretty_print(const std::string &name, size_t num_chars,
+                    std::pair<event_aggregate, size_t> result) {
+  const auto &agg = result.first;
+  size_t N = result.second;
+  num_chars *= N;
+  printf("%-40s : %8.2f ns %8.2f GB/s", name.c_str(),
+         agg.elapsed_ns() / num_chars, num_chars / agg.elapsed_ns());
+  if (collector.has_events()) {
+    printf(" %8.2f GHz %8.2f cycles/char %8.2f ins./char %8.2f i/c",
+           agg.cycles() / agg.elapsed_ns(), agg.cycles() / num_chars,
+           agg.instructions() / num_chars, agg.instructions() / agg.cycles());
+  }
+  printf("\n");
+  return num_chars / agg.elapsed_ns();
+}
+
+template <class function_type>
+std::pair<event_aggregate, size_t>
+bench(const function_type &&function, size_t min_repeat = 100,
+      size_t min_time_ns = 40'000'000, size_t max_repeat = 10000000) {
+  size_t N = min_repeat;
+  if (N == 0) {
+    N = 1;
+  }
+  event_aggregate warm_aggregate{};
+  for (size_t i = 0; i < N; i++) {
+    std::atomic_thread_fence(std::memory_order_acquire);
+    collector.start();
+    function();
+    std::atomic_thread_fence(std::memory_order_release);
+    event_count allocate_count = collector.end();
+    warm_aggregate << allocate_count;
+    if ((i + 1 == N) && (warm_aggregate.total_elapsed_ns() < min_time_ns) &&
+        (N < max_repeat)) {
+      N *= 10;
+    }
+  }
+  event_aggregate aggregate{};
+  for (size_t i = 0; i < 10; i++) {
+    std::atomic_thread_fence(std::memory_order_acquire);
+    collector.start();
+    for (size_t i = 0; i < N; i++) {
+      function();
+    }
+    std::atomic_thread_fence(std::memory_order_release);
+    event_count allocate_count = collector.end();
+    aggregate << allocate_count;
+  }
+  return {aggregate, N};
+}
+
+void run_benchmarks() {
+  std::vector<Car> source = generate_random_cars(100000);
+  simdjson::builder::string_builder sb;
+  size_t volume = serialize(sb, source).size();
+
+  pretty_print("string_builder", volume, bench([&source, &sb]() -> size_t {
+                 return serialize(sb, source).size();
+               }));
+}
+
+int main() {
+  for (size_t trial = 0; trial < 3; trial++) {
+    printf("Trial %zu:\n", trial + 1);
+    run_benchmarks();
+    printf("\n");
+  }
+  return EXIT_SUCCESS;
+}

benchmark/distinct_user_id/yyjson.h

@@ -44,7 +44,10 @@ struct yyjson_base {
 
 struct yyjson : yyjson_base {
   bool run(simdjson::padded_string &json, std::vector<uint64_t> &result) {
-    return yyjson_base::run(yyjson_read(json.data(), json.size(), 0), result);
+    yyjson_doc *doc = yyjson_read(json.data(), json.size(), 0);
+    bool b = yyjson_base::run(doc, result);
+    yyjson_doc_free(doc);
+    return b;
   }
 };
 BENCHMARK_TEMPLATE(distinct_user_id, yyjson)->UseManualTime();
@@ -52,11 +55,15 @@ BENCHMARK_TEMPLATE(distinct_user_id, yyjson)->UseManualTime();
 #if SIMDJSON_COMPETITION_ONDEMAND_INSITU
 struct yyjson_insitu : yyjson_base {
   bool run(simdjson::padded_string &json, std::vector<uint64_t> &result) {
-    return yyjson_base::run(yyjson_read_opts(json.data(), json.size(), YYJSON_READ_INSITU, 0, 0), result);
+    yyjson_doc *doc = yyjson_read_opts(json.data(), json.size(), YYJSON_READ_INSITU, 0, 0);
+    bool b = yyjson_base::run(doc, result);
+    yyjson_doc_free(doc);
+    return b;
   }
 };
 BENCHMARK_TEMPLATE(distinct_user_id, yyjson_insitu)->UseManualTime();
 #endif // SIMDJSON_COMPETITION_ONDEMAND_INSITU
+
 } // namespace distinct_user_id
 
 #endif // SIMDJSON_COMPETITION_YYJSON

benchmark/dom/parse_stream.cpp

@@ -25,12 +25,11 @@ int main(int argc, char *argv[]) {
     exit(1);
   }
   const char *filename = argv[1];
-  auto v = simdjson::padded_string::load(filename);
+  simdjson::padded_string p;
-  if (v.error()) {
+  if (simdjson::padded_string::load(filename).get(p)) {
     std::cerr << "Could not load the file " << filename << std::endl;
     return EXIT_FAILURE;
   }
-  const simdjson::padded_string& p = v.value_unsafe();
   if (test_baseline) {
     std::wclog << "Baseline: Getline + normal parse... " << std::endl;
     std::cout << "Gigabytes/second\t"

benchmark/find_tweet/yyjson.h

@@ -36,18 +36,26 @@ struct yyjson_base {
 
 struct yyjson : yyjson_base {
   bool run(simdjson::padded_string &json, uint64_t find_id, std::string_view &result) {
-    return yyjson_base::run(yyjson_read(json.data(), json.size(), 0), find_id, result);
+    yyjson_doc *doc = yyjson_read(json.data(), json.size(), 0);
+    bool b = yyjson_base::run(doc, find_id, result);
+    yyjson_doc_free(doc);
+    return b;
   }
 };
 BENCHMARK_TEMPLATE(find_tweet, yyjson)->UseManualTime();
+
 #if SIMDJSON_COMPETITION_ONDEMAND_INSITU
 struct yyjson_insitu : yyjson_base {
   bool run(simdjson::padded_string &json, uint64_t find_id, std::string_view &result) {
-    return yyjson_base::run(yyjson_read_opts(json.data(), json.size(), YYJSON_READ_INSITU, 0, 0), find_id, result);
+    yyjson_doc *doc = yyjson_read_opts(json.data(), json.size(), YYJSON_READ_INSITU, 0, 0);
+    bool b = yyjson_base::run(doc, find_id, result);
+    yyjson_doc_free(doc);
+    return b;
   }
 };
 BENCHMARK_TEMPLATE(find_tweet, yyjson_insitu)->UseManualTime();
 #endif // SIMDJSON_COMPETITION_ONDEMAND_INSITU
+
 } // namespace find_tweet
 
 #endif // SIMDJSON_COMPETITION_YYJSON

benchmark/from/CMakeLists.txt

@@ -0,0 +1,15 @@
+# Executable
+add_executable(from_benchmark from_benchmark.cpp)
+
+# Compile for C++20.
+if(CMAKE_CXX_STANDARD LESS 20)
+  target_compile_features(from_benchmark PRIVATE cxx_std_20)
+endif()
+# Check if -march=native is supported
+include(CheckCXXCompilerFlag)
+check_cxx_compiler_flag("-march=native" SIMDJSON_SUPPORTS_MARCH_NATIVE)
+if(SIMDJSON_SUPPORTS_MARCH_NATIVE)
+  target_compile_options(from_benchmark PRIVATE -march=native)
+endif()
+
+target_include_directories(from_benchmark PRIVATE ${CMAKE_CURRENT_LIST_DIR}/..)

benchmark/from/benchmark_helpers.h

@@ -0,0 +1,77 @@
+#ifndef BENCHMARK_HELPERS_H
+#define BENCHMARK_HELPERS_H
+
+#include "event_counter.h"
+#include <atomic>
+
+event_collector collector;
+
+template <class function_type>
+std::pair<event_aggregate, size_t>
+bench(const function_type &&function, size_t min_repeat = 10,
+      size_t min_time_ns = 40'000'000, size_t max_repeat = 10000000) {
+  size_t N = min_repeat;
+  if (N == 0) {
+    N = 1;
+  }
+  event_aggregate warm_aggregate{};
+  for (size_t i = 0; i < N; i++) {
+    std::atomic_thread_fence(std::memory_order_acquire);
+    collector.start();
+    function();
+    std::atomic_thread_fence(std::memory_order_release);
+    event_count allocate_count = collector.end();
+    warm_aggregate << allocate_count;
+    if ((i + 1 == N) && (warm_aggregate.total_elapsed_ns() < min_time_ns) &&
+        (N < max_repeat)) {
+      N *= 10;
+    }
+  }
+  event_aggregate aggregate{};
+  for (size_t i = 0; i < 10; i++) {
+    std::atomic_thread_fence(std::memory_order_acquire);
+    collector.start();
+    for (size_t i = 0; i < N; i++) {
+      function();
+    }
+    std::atomic_thread_fence(std::memory_order_release);
+    event_count allocate_count = collector.end();
+    aggregate << allocate_count;
+  }
+  return {aggregate, N};
+}
+
+double pretty_print(const std::string &name, size_t num_chars,
+                    std::pair<event_aggregate, size_t> result) {
+  const auto &agg = result.first;
+  size_t N = result.second;
+  num_chars *= N;
+  printf("%-40s : %8.2f ns %8.2f GB/s", name.c_str(),
+         agg.elapsed_ns() / num_chars, num_chars / agg.elapsed_ns());
+  if (collector.has_events()) {
+    printf(" %8.2f GHz %8.2f cycles/char %8.2f ins./char %8.2f i/c",
+           agg.cycles() / agg.elapsed_ns(), agg.cycles() / num_chars,
+           agg.instructions() / num_chars, agg.instructions() / agg.cycles());
+  }
+  printf("\n");
+  return num_chars / agg.elapsed_ns();
+}
+
+double pretty_print_array(const std::string &name, size_t num_chars, size_t num_elements,
+                    std::pair<event_aggregate, size_t> result) {
+  const auto &agg = result.first;
+  size_t N = result.second;
+  num_chars *= N;
+  printf("%-40s : %8.2f ns/char %8.2f ns/value %8.2f GB/s", name.c_str(),
+         agg.elapsed_ns() / num_chars, agg.elapsed_ns() / num_elements, num_chars / agg.elapsed_ns());
+  if (collector.has_events()) {
+    printf(" %8.2f GHz %8.2f cycles/char %8.2f ins./char %8.2f ins./value %8.2f i/c",
+           agg.cycles() / agg.elapsed_ns(), agg.cycles() / num_chars,
+           agg.instructions() / num_chars, agg.instructions() / num_elements, agg.instructions() / agg.cycles());
+  }
+  printf("\n");
+  return num_chars / agg.elapsed_ns();
+}
+
+
+#endif

benchmark/from/car_helpers.h

@@ -0,0 +1,146 @@
+#ifndef CAR_HELPERS_H
+#define CAR_HELPERS_H
+
+#include <iomanip>
+#include <random>
+#include <sstream>
+#include <vector>
+
+#include <simdjson.h>
+
+struct Car {
+  std::string make;
+  std::string model;
+  int64_t year; // We deliberately do not include the tire pressure.
+};
+
+using namespace simdjson;
+
+std::string random_car_json() {
+  static const std::vector<std::string> makes = {"Toyota", "Honda", "Ford",
+                                                 "BMW", "Mazda"};
+  static const std::vector<std::string> models = {"Camry", "Civic", "Focus",
+                                                  "320i", "3"};
+  static thread_local std::mt19937 rng{std::random_device{}()};
+  std::uniform_int_distribution<int> make_dist(0, makes.size() - 1);
+  std::uniform_int_distribution<int> model_dist(0, models.size() - 1);
+  std::uniform_int_distribution<int> year_dist(2000, 2025);
+  std::uniform_real_distribution<double> pressure_dist(30.0, 45.0);
+
+  std::ostringstream oss;
+  oss << R"({ "make": ")" << makes[make_dist(rng)] << R"(", "model": ")"
+      << models[model_dist(rng)] << R"(",  "year": )" << year_dist(rng)
+      << R"(, "tire_pressure": [ )" << std::fixed << std::setprecision(1)
+      << pressure_dist(rng) << ", " << pressure_dist(rng) << R"( ] })";
+  return oss.str();
+}
+
+std::string generate_car_json_stream(size_t N) {
+  std::ostringstream oss;
+  for (size_t i = 0; i < N; ++i) {
+    oss << random_car_json();
+    oss << "\n";
+  }
+  return oss.str();
+}
+
+std::string generate_car_json_array(size_t N) {
+  std::ostringstream oss;
+  oss << "[\n";
+  for (size_t i = 0; i < N; ++i) {
+    oss << random_car_json();
+    if (i < N - 1) {
+      oss << ",";
+    }
+    oss << "\n";
+  }
+  oss << "]";
+  return oss.str();
+}
+
+// We want to maximize C++ portability, but this is not needed with static
+// reflection (C++26).
+template <>
+simdjson_inline simdjson_result<Car>
+simdjson::ondemand::document::get() & noexcept {
+  ondemand::object obj;
+  auto error = get_object().get(obj);
+  if (error) {
+    return error;
+  }
+  Car car;
+  if ((error = obj["make"].get_string(car.make))) {
+    return error;
+  }
+  if ((error = obj["model"].get_string(car.model))) {
+    return error;
+  }
+  if ((error = obj["year"].get_int64().get(car.year))) {
+    return error;
+  }
+  return car;
+}
+
+template <>
+simdjson_inline simdjson_result<Car> simdjson::ondemand::value::get() noexcept {
+  ondemand::object obj;
+  auto error = get_object().get(obj);
+  if (error) {
+    return error;
+  }
+  Car car;
+  if ((error = obj["make"].get_string(car.make))) {
+    return error;
+  }
+  if ((error = obj["model"].get_string(car.model))) {
+    return error;
+  }
+  if ((error = obj["year"].get_int64().get(car.year))) {
+    return error;
+  }
+  return car;
+}
+
+template <>
+simdjson_inline simdjson_result<Car>
+simdjson::ondemand::document_reference::get() & noexcept {
+  ondemand::object obj;
+  auto error = get_object().get(obj);
+  if (error) {
+    return error;
+  }
+  Car car;
+  if ((error = obj["make"].get_string(car.make))) {
+    return error;
+  }
+  if ((error = obj["model"].get_string(car.model))) {
+    return error;
+  }
+  if ((error = obj["year"].get_int64().get(car.year))) {
+    return error;
+  }
+  return car;
+}
+
+template <>
+simdjson_inline simdjson_result<Car>
+simdjson::ondemand::document_reference::get() && noexcept {
+  ondemand::object obj;
+  auto error = get_object().get(obj);
+  if (error) {
+    return error;
+  }
+  Car car;
+  if ((error = obj["make"].get_string(car.make))) {
+    return error;
+  }
+  if ((error = obj["model"].get_string(car.model))) {
+    return error;
+  }
+  if ((error = obj["year"].get_int64().get(car.year))) {
+    return error;
+  }
+  return car;
+}
+
+#endif

benchmark/from/from_benchmark.cpp

@@ -0,0 +1,132 @@
+// We are going to assume C++20.
+
+#include <cstdint>
+#include <cstdio>
+#include <cstdlib>
+#include <simdjson.h>
+#include <string>
+
+#include "benchmark_helpers.h"
+#include "car_helpers.h"
+
+using namespace simdjson;
+
+void run_benchmarks() {
+  printf("Running benchmarks on tiny input...\n");
+  simdjson::padded_string json =
+      R"({ "make": "Toyota", "model": "Camry",  "year": 2018, "tire_pressure": [ 40.1, 39.9 ] })"_padded;
+  volatile size_t dummy = 0;
+  ondemand::parser parser;
+
+  // Classic On-Demand
+  pretty_print("simdjson classic", json.size(),
+               bench([&json, &dummy, &parser]() {
+                 ondemand::document doc = parser.iterate(json);
+                 Car car = doc.get<Car>();
+                 dummy = dummy + car.year;
+               }));
+
+  // Benchmark simdjson::from() without parser
+  pretty_print("simdjson::from<Car>() (no parser)", json.size(),
+               bench([&json, &dummy]() {
+                 Car car = simdjson::from(json);
+                 dummy = dummy + car.year;
+               }));
+
+  // Benchmark simdjson::from() with parser
+  pretty_print("simdjson::from<Car>() (with parser)", json.size(),
+               bench([&json, &dummy, &parser]() {
+                 Car car = simdjson::from(parser, json);
+                 dummy = dummy + car.year;
+               }));
+}
+
+void run_array_benchmarks() {
+  printf("Running benchmarks on large array...\n");
+  size_t N = 1'000'000;
+  simdjson::padded_string json = generate_car_json_array(N);
+  volatile size_t dummy = 0;
+  ondemand::parser parser;
+
+  // Classic On-Demand
+  pretty_print_array("simdjson classic", json.size(), N,
+                     bench([&json, &dummy, &parser]() {
+                       dummy = 0;
+                       ondemand::document doc = parser.iterate(json);
+                       ondemand::array array = doc.get_array();
+                       for (auto value : array) {
+                         Car car = value.get<Car>();
+                         dummy = dummy + car.year;
+                       }
+                     }));
+
+  // from with array
+  pretty_print_array("simdjson::from(json).array()", json.size(), N,
+                     bench([&json, &dummy, &parser]() {
+                       dummy = 0;
+
+                       for (auto value : simdjson::from(json).array()) {
+                         Car car = value.get<Car>();
+                         dummy = dummy + car.year;
+                       }
+                     }));
+#if SIMDJSON_SUPPORTS_RANGES_FROM
+  // Benchmark simdjson::from() without parser (EXPERIMENTAL)
+  pretty_print_array("simdjson::from<Car>() (experimental, no parser)",
+                     json.size(), N, bench([&json, &dummy]() {
+                       dummy = 0;
+                       for (Car car :
+                            simdjson::from(json) | simdjson::as<Car>()) {
+                         dummy = dummy + car.year;
+                       }
+                     }));
+
+  // Benchmark simdjson::from() with parser (EXPERIMENTAL)
+  pretty_print_array("simdjson::from<Car>() (experimental, with parser)",
+                     json.size(), N, bench([&json, &dummy, &parser]() {
+                       dummy = 0;
+                       for (Car car : simdjson::from(parser, json) |
+                                          simdjson::as<Car>()) {
+                         dummy = dummy + car.year;
+                       }
+                     }));
+#endif // SIMDJSON_SUPPORTS_RANGES_FROM
+}
+
+void run_stream_benchmarks() {
+  printf("Running stream benchmarks...\n");
+  simdjson::padded_string json = generate_car_json_stream(1'000'000);
+  volatile size_t dummy = 0;
+  ondemand::parser parser;
+
+  // Classic On-Demand
+  pretty_print("simdjson classic", json.size(),
+               bench([&json, &dummy, &parser]() {
+                 ondemand::document_stream stream = parser.iterate_many(json);
+                 for (auto doc : stream) {
+                   Car car = doc.get<Car>();
+                   dummy = dummy + car.year;
+                 }
+               }));
+  // from_many
+  pretty_print("simdjson with thread local", json.size(),
+               bench([&json, &dummy, &parser]() {
+                 ondemand::document_stream stream =
+                     ondemand::parser::get_parser().iterate_many(json);
+                 for (auto doc : stream) {
+                   Car car = doc.get<Car>();
+                   dummy = dummy + car.year;
+                 }
+               }));
+}
+
+int main() {
+  for (size_t trial = 0; trial < 3; trial++) {
+    printf("Trial %zu:\n", trial + 1);
+    run_array_benchmarks();
+    run_stream_benchmarks();
+    run_benchmarks();
+    printf("\n");
+  }
+  return EXIT_SUCCESS;
+}

benchmark/get_corpus_benchmark.cpp

@@ -9,7 +9,11 @@ simdjson_never_inline
 double bench(std::string filename, simdjson::padded_string& p) {
   std::chrono::time_point<std::chrono::steady_clock> start_clock =
       std::chrono::steady_clock::now();
-  simdjson::padded_string::load(filename).value_unsafe().swap(p);
+  auto error = simdjson::padded_string::load(filename).get(p);
+  if(error) {
+    std::cerr << simdjson::error_message(error) << std::endl;
+    std::abort();
+  }
   std::chrono::time_point<std::chrono::steady_clock> end_clock =
       std::chrono::steady_clock::now();
   std::chrono::duration<double> elapsed = end_clock - start_clock;

benchmark/json2msgpack/yyjson.h

@@ -100,6 +100,7 @@ struct yyjson : yyjson2msgpack {
            std::string_view &result) {
     yyjson_doc *doc = yyjson_read(json.data(), json.size(), 0);
     result = to_msgpack(doc, reinterpret_cast<uint8_t*>(buffer));
+    yyjson_doc_free(doc);
     return true;
   }
 };
@@ -113,6 +114,7 @@ struct yyjson_insitu : yyjson2msgpack {
     yyjson_doc *doc =
         yyjson_read_opts(json.data(), json.size(), YYJSON_READ_INSITU, 0, 0);
     result = to_msgpack(doc, reinterpret_cast<uint8_t*>(buffer));
+    yyjson_doc_free(doc);
     return true;
   }
 };
@@ -120,4 +122,4 @@ BENCHMARK_TEMPLATE(json2msgpack, yyjson_insitu)->UseManualTime();
 #endif // SIMDJSON_COMPETITION_ONDEMAND_INSITU
 } // namespace json2msgpack
 
-#endif // SIMDJSON_COMPETITION_YYJSON
+#endif // SIMDJSON_COMPETITION_YYJSON

benchmark/kostya/yyjson.h

@@ -49,18 +49,26 @@ struct yyjson_base {
 
 struct yyjson : yyjson_base {
   bool run(simdjson::padded_string &json, std::vector<point> &result) {
-    return yyjson_base::run(yyjson_read(json.data(), json.size(), 0), result);
+    yyjson_doc *doc = yyjson_read(json.data(), json.size(), 0);
+    bool b = yyjson_base::run(doc, result);
+    yyjson_doc_free(doc);
+    return b;
   }
 };
 BENCHMARK_TEMPLATE(kostya, yyjson)->UseManualTime();
+
 #if SIMDJSON_COMPETITION_ONDEMAND_INSITU
 struct yyjson_insitu : yyjson_base {
   bool run(simdjson::padded_string &json, std::vector<point> &result) {
-    return yyjson_base::run(yyjson_read_opts(json.data(), json.size(), YYJSON_READ_INSITU, 0, 0), result);
+    yyjson_doc *doc = yyjson_read_opts(json.data(), json.size(), YYJSON_READ_INSITU, 0, 0);
+    bool b = yyjson_base::run(doc, result);
+    yyjson_doc_free(doc);
+    return b;
   }
 };
 BENCHMARK_TEMPLATE(kostya, yyjson_insitu)->UseManualTime();
 #endif // SIMDJSON_COMPETITION_ONDEMAND_INSITU
+
 } // namespace kostya
 
 #endif // SIMDJSON_COMPETITION_YYJSON

benchmark/large_random/yyjson.h

@@ -47,18 +47,26 @@ struct yyjson_base {
 
 struct yyjson : yyjson_base {
   bool run(simdjson::padded_string &json, std::vector<point> &result) {
-    return yyjson_base::run(yyjson_read(json.data(), json.size(), 0), result);
+    yyjson_doc *doc = yyjson_read(json.data(), json.size(), 0);
+    bool b = yyjson_base::run(doc, result);
+    yyjson_doc_free(doc);
+    return b;
   }
 };
 BENCHMARK_TEMPLATE(large_random, yyjson)->UseManualTime();
+
 #if SIMDJSON_COMPETITION_ONDEMAND_INSITU
 struct yyjson_insitu : yyjson_base {
   bool run(simdjson::padded_string &json, std::vector<point> &result) {
-    return yyjson_base::run(yyjson_read_opts(json.data(), json.size(), YYJSON_READ_INSITU, 0, 0), result);
+    yyjson_doc *doc = yyjson_read_opts(json.data(), json.size(), YYJSON_READ_INSITU, 0, 0);
+    bool b = yyjson_base::run(doc, result);
+    yyjson_doc_free(doc);
+    return b;
   }
 };
 BENCHMARK_TEMPLATE(large_random, yyjson_insitu)->UseManualTime();
 #endif // SIMDJSON_COMPETITION_ONDEMAND_INSITU
+
 } // namespace large_random
 
 #endif // SIMDJSON_COMPETITION_YYJSON

benchmark/partial_tweets/yyjson.h

@@ -62,19 +62,26 @@ struct yyjson_base {
 
 struct yyjson : yyjson_base {
   bool run(simdjson::padded_string &json, std::vector<tweet<std::string_view>> &result) {
-    return yyjson_base::run(yyjson_read(json.data(), json.size(), 0), result);
+    yyjson_doc *doc = yyjson_read(json.data(), json.size(), 0);
+    bool b = yyjson_base::run(doc, result);
+    yyjson_doc_free(doc);
+    return b;
   }
 };
 BENCHMARK_TEMPLATE(partial_tweets, yyjson)->UseManualTime();
+
 #if SIMDJSON_COMPETITION_ONDEMAND_INSITU
 struct yyjson_insitu : yyjson_base {
   bool run(simdjson::padded_string &json, std::vector<tweet<std::string_view>> &result) {
-    return yyjson_base::run(yyjson_read_opts(json.data(), json.size(), YYJSON_READ_INSITU, 0, 0), result);
+    yyjson_doc *doc = yyjson_read_opts(json.data(), json.size(), YYJSON_READ_INSITU, 0, 0);
+    bool b = yyjson_base::run(doc, result);
+    yyjson_doc_free(doc);
+    return b;
   }
 };
 BENCHMARK_TEMPLATE(partial_tweets, yyjson_insitu)->UseManualTime();
 #endif // SIMDJSON_COMPETITION_ONDEMAND_INSITU
+
 } // namespace partial_tweets
 
 #endif // SIMDJSON_COMPETITION_YYJSON
-

benchmark/static_reflect/CMakeLists.txt

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

benchmark/top_tweet/yyjson.h

@@ -51,18 +51,26 @@ struct yyjson_base {
 
 struct yyjson : yyjson_base {
   bool run(simdjson::padded_string &json, int64_t max_retweet_count, top_tweet_result<StringType> &result) {
-    return yyjson_base::run(yyjson_read(json.data(), json.size(), 0), max_retweet_count, result);
+    yyjson_doc *doc = yyjson_read(json.data(), json.size(), 0);
+    bool b = yyjson_base::run(doc, max_retweet_count, result);
+    yyjson_doc_free(doc);
+    return b;
   }
 };
 BENCHMARK_TEMPLATE(top_tweet, yyjson)->UseManualTime();
+
 #if SIMDJSON_COMPETITION_ONDEMAND_INSITU
 struct yyjson_insitu : yyjson_base {
   bool run(simdjson::padded_string &json, int64_t max_retweet_count, top_tweet_result<StringType> &result) {
-    return yyjson_base::run(yyjson_read_opts(json.data(), json.size(), YYJSON_READ_INSITU, 0, 0), max_retweet_count, result);
+    yyjson_doc *doc = yyjson_read_opts(json.data(), json.size(), YYJSON_READ_INSITU, 0, 0);
+    bool b = yyjson_base::run(doc, max_retweet_count, result);
+    yyjson_doc_free(doc);
+    return b;
   }
 };
 BENCHMARK_TEMPLATE(top_tweet, yyjson_insitu)->UseManualTime();
 #endif // SIMDJSON_COMPETITION_ONDEMAND_INSITU
+
 } // namespace top_tweet
 
 #endif // SIMDJSON_COMPETITION_YYJSON

cmake/developer-options.cmake

@@ -4,7 +4,7 @@
 add_library(simdjson-internal-flags INTERFACE)
 if(NOT DEFINED CMAKE_POSITION_INDEPENDENT_CODE)
   # We default to ON for all targets, so that we can use the library in shared libraries.
-  set_target_properties(simdjson-internal-flags PROPERTIES POSITION_INDEPENDENT_CODE ON)
+  set_target_properties(simdjson-internal-flags PROPERTIES INTERFACE_POSITION_INDEPENDENT_CODE ON)
 endif(NOT DEFINED CMAKE_POSITION_INDEPENDENT_CODE)
 
 option(SIMDJSON_CHECK_EOF "Check for the end of the input buffer. The setting is unnecessary since we require padding of the inputs. You should expect tests to fail with this option turned on." OFF)
@@ -32,6 +32,9 @@ undefined behavior.")
     link_libraries(
         -fsanitize=address -fno-omit-frame-pointer -fno-sanitize-recover=all
     )
+  elseif (CMAKE_CXX_COMPILER_ID STREQUAL "MSVC")
+    add_compile_options(-fsanitize=address)
+    link_libraries(-fsanitize=address)
   else()
     message(
         STATUS
@@ -171,6 +174,10 @@ else()
       -Werror -Wall -Wextra -Weffc++ -Wsign-compare -Wshadow -Wwrite-strings
       -Wpointer-arith -Winit-self -Wconversion -Wno-sign-conversion
   )
+  if(CMAKE_CXX_STANDARD VERSION_GREATER_EQUAL 20)
+    target_compile_options(simdjson-internal-flags INTERFACE -Wctad-maybe-unsupported)
+  endif()
+
 endif()
 
 option(SIMDJSON_GLIBCXX_ASSERTIONS "Set _GLIBCXX_ASSERTIONS" OFF)

cmake/exception-flags.cmake

@@ -17,8 +17,9 @@ editing CMAKE_CXX_FLAGS")
     # /EHc used in conjection with /EHs indicates that extern "C" functions
     # never throw (terminate-on-throw)
     # Here, we disable both with the - argument negation operator
-    string(REPLACE "/EHsc" "/EHs-c-" CMAKE_CXX_FLAGS ${CMAKE_CXX_FLAGS})
+    if(CMAKE_CXX_FLAGS)
-
+        string(REPLACE "/EHsc" "/EHs-c-" CMAKE_CXX_FLAGS ${CMAKE_CXX_FLAGS})
+    endif()
     # Because we cannot change the flag above on an individual target (yet), the
     # definition below must similarly be added globally
     add_definitions(-D_HAS_EXCEPTIONS=0)

cmake/toolchains-ci/riscv64-linux-gnu.cmake

@@ -0,0 +1,4 @@
+set(CMAKE_SYSTEM_NAME Linux)
+set(CMAKE_SYSTEM_PROCESSOR riscv64)
+
+set(CMAKE_CROSSCOMPILING_EMULATOR "qemu-riscv64-static")

doc/basics_doxygen.md

@@ -1,5 +1,8 @@
 We take our documentation seriously. Please start reading the documentation before you attempt to use simdjson. We hope you will enjoy reading us.
 
-* Basics: https://github.com/simdjson/simdjson/blob/master/doc/basics.md is an overview of how to use simdjson and its APIs.
+* [Basics](doc/basics.md) is an overview of how to use simdjson and its APIs.
-* iterate_many: https://github.com/simdjson/simdjson/blob/master/doc/iterate_many.md describes an interface providing features to work with files or streams containing multiple small JSON documents. As fast and convenient as possible.
+* [Builder](doc/builder.md) is an overview of how to efficiently write JSON strings using simdjson.
-* Performance: https://github.com/simdjson/simdjson/blob/master/doc/performance.md shows some more advanced scenarios and how to tune for them.
+* [Performance](doc/performance.md) shows some more advanced scenarios and how to tune for them.
+* [Implementation Selection](doc/implementation-selection.md) describes runtime CPU detection and
+  how you can work with it.
+* [API](https://simdjson.github.io/simdjson/) contains the automatically generated API documentation.

doc/builder.md

@@ -14,6 +14,7 @@ speed and high convenience.
   * [C++26 static reflection](#c--26-static-reflection)
     + [Without `string_buffer` instance](#without--string-buffer--instance)
     + [Without `string_buffer` instance but with explicit error handling](#without--string-buffer--instance-but-with-explicit-error-handling)
+    + [Pretty formatted (fractured JSON)](#pretty-formatted-fractured-json)
 
 Overview: string_builder
 ---------------------------
@@ -34,32 +35,33 @@ It has the following methods to add content to the string:
 - `append_null()`: Appends the string "null" to the JSON buffer.
 - `clear()`: Clears the contents of the JSON buffer, resetting the position to 0 while retaining the allocated capacity.
 - `escape_and_append(std::string_view input)`: Appends a string view to the JSON buffer after escaping special characters (e.g., quotes, backslashes) as required by JSON.
-- `escape_and_append_with_quotes(std::string_view input)` Appends a string view surrounded by double quotes (e.g., "input") to the JSON buffer after escaping special characters.
+- `escape_and_append_with_quotes(std::string_view input)` Appends a string view surrounded by double quotes (e.g., "input") to the JSON buffer after escaping special characters. For constant strings, you may also do `escape_and_append_with_quotes<"mystring">()`.
-Parameters:
 - `escape_and_append_with_quotes(char input)`: Appends a single character surrounded by double quotes (e.g., "c") to the JSON buffer after escaping it if necessary.
 - `append_raw(const char *c)`: Appends a null-terminated C string directly to the JSON buffer without escaping.
 - `append_raw(std::string_view input)`: Appends a string view directly to the JSON buffer without escaping.
 - `append_raw(const char *str, size_t len)`: Appends a specified number of characters from a C string directly to the JSON
+- `append_key_value(key,value)`: Appends a key and a value (`"json":somevalue`)
+- `append_key_value<"mykey">(value)`: Appends a key and a value (`"json":somevalue`), useful when the key is a compile-time constant (C++20).
 
-After writting the content, if you have reasons to believe that the content might violate UTF-8 conventions, you can check it as follows:
+After writing the content, if you have reasons to believe that the content might violate UTF-8 conventions, you can check it as follows:
 
 - `validate_unicode()`: Checks if the content in the JSON buffer is valid UTF-8. Returns: true if the content is valid UTF-8, false otherwise.
 
 You might need to do unicode validation if you have strings in your data structures containing
-malformed UTF-8.
+malformed UTF-8. Note that we do not automatically call `validate_unicode()`.
 
 Once you are satisfied, you can recover the string as follows:
 
 - `operator std::string()`: Converts the JSON buffer to an std::string. (Might throw if an error occurred.)
 - `operator std::string_view()`: Converts the JSON buffer to an std::string_view.  (Might throw if an error occurred.)
-- `view()`: Returns a view of the written JSON buffer as a `simdjson_result<std::string_view>`.
+- `view()`: Returns a view of the written JSON buffer as a `simdjson_result<std::string_view>` (C++20).
 
-The later method (`view()`) is recommended.
+The later method (`view()`) is recommended.  For performance reasons, we expect you to explicitly call `validate_unicode()` as needed (e.g., prior to calling `view()`).
 
 Example: string_builder
 ---------------------------
 
-```C++
+```cpp
 struct Car {
     std::string make;
     std::string model;
@@ -109,6 +111,9 @@ bool car_test() {
 }
 ```
 
+
+
+
 The `string_builder` constructor takes an optional parameter which specifies the initial
 memory allocation in byte. If you know approximately the size of your JSON output, you can
 pass this value as a parameter (e.g., `simdjson::builder::string_builder sb{1233213}`).
@@ -124,6 +129,100 @@ The `string_builder` might throw an exception in case of error when you cast it
 
 In all cases, the `std::string_view` instance depends the corresponding `string_builder` instance.
 
+### C++20
+
+
+
+If you have C++20, you can simplify the code, as the `std::vector<double>` is automatically supported. Further, we can pass the keys (which are compile-time
+constant) as template parameter (for improved performance).
+
+```cpp
+    Car c = {"Toyota", "Corolla", 2017, {30.0,30.2,30.513,30.79}};
+    simdjson::builder::string_builder sb;
+    sb.start_object();
+    sb.append_key_value<"make">(c.make);
+    sb.append_comma();
+    sb.append_key_value<"model">(c.model);
+    sb.append_comma();
+    sb.append_key_value<"year">(c.year);
+    sb.append_comma();
+    sb.append_key_value<"tire_pressure">(c.tire_pressure);
+    sb.end_object();
+    std::string_view p = sb.view();
+```
+
+With C++20, you can similarly handle standard containers transparently.
+For example, you can serialize `std::map<std::string,T>` types.
+
+```cpp
+    std::map<std::string,double> c = {{"key1", 1}, {"key2", 1}};
+    simdjson::builder::string_builder sb;
+    sb.append(c);
+    std::string_view p = sb.view();
+```
+
+You can also serialize `std::vector<T>` types.
+
+```cpp
+    std::vector<std::vector<double>> c = {{1.0, 2.0}, {3.0, 4.0}};
+    simdjson::builder::string_builder sb;
+    sb.append(c);
+    std::string_view p = sb.view();
+```
+
+You can also skip the creation for the `string_builder` instance in such simple cases.
+
+```cpp
+std::vector<std::vector<double>> c = {{1.0, 2.0}, {3.0, 4.0}};
+std::string json = simdjson::to_json(c);
+```
+
+We also have an overload for when you want to reuse the same `std::string` instance:
+
+
+```cpp
+std::vector<std::vector<double>> c = {{1.0, 2.0}, {3.0, 4.0}};
+std::string json;
+auto error = simdjson::to_json(c, json);
+if(error) { /* there was an error */ }
+```
+
+
+We do recommend that you create and reuse the `string_builder` instance for performance
+reasons.
+
+You can also add custom serialization functions using a `tag_invoke` function.
+For example, the following
+function will allow you to serialize instances of the type `Car`.
+
+```cpp
+#include <simdjson>
+
+struct Car {
+  std::string make;
+  std::string model;
+  int64_t year;
+  std::vector<float> tire_pressure;
+};
+
+namespace simdjson {
+
+template <typename builder_type>
+void tag_invoke(serialize_tag, builder_type &builder, const Car& car) {
+  builder.start_object();
+  builder.append_key_value("make", car.make);
+  builder.append_comma();
+  builder.append_key_value("model", car.model);
+  builder.append_comma();
+  builder.append_key_value("year", car.year);
+  builder.append_comma();
+  builder.append_key_value("tire_pressure", car.tire_pressure);
+  builder.end_object();
+}
+
+} // namespace simdjson
+```
+
 C++26 static reflection
 ------------------------
 
@@ -165,7 +264,7 @@ automatically. In most cases, it should work automatically:
 
 In some instances, you might want to create a string directly from your own data type.
 You can create a string directly, without an explicit `string_builder` instance
-with the `simdjson::builder::to_json_string` function.
+with the `simdjson::to_json` template function.
 (Under the hood a `string_builder` instance may still be created.)
 
 ```cpp
@@ -178,14 +277,45 @@ with the `simdjson::builder::to_json_string` function.
 
     void f() {
         Car c = {"Toyota", "Corolla", 2017, {30.0,30.2,30.513,30.79}};
-        std::string json = simdjson::builder::to_json_string(c);
+        std::string json = simdjson::to_json(c);
     }
 ```
 
 If you know the output size, in bytes, of your JSON string, you may
-pass it as a second parameter (e.g., `simdjson::builder::to_json_string(c, 31123)`).
+pass it as a second parameter (e.g., `simdjson::to_json(c, 31123)`).
 
+Sometimes you may want to reuse the same `std::string` instance. We
+have an overload for this purpose:
 
+```cpp
+Car c = {"Toyota", "Corolla", 2017, {30.0,30.2,30.513,30.79}};
+std::string s;
+auto error = simdjson::to_json(c, s);
+if(error) { /* there was an error */ }
+```
+
+You can then also add a third parameter for the expected output size in bytes.
+
+### Extracting just some fields
+In some instances, your class might have many fields that you do not want to serialize.
+You can achieve this result with the `simdjson::extract_from` template. In the following
+example, we serialize only the `year` and `price` fields on the `Car` instance.
+```cpp
+struct Car {
+    std::string make;
+    std::string model;
+    int year;
+    double price;
+    bool electric;
+};
+Car car{"Ford", "F-150", 2024, 55000.0, false};
+// Extract year and price
+std::string json_result = simdjson::extract_from<"year", "price">(car);
+// Alternatively:
+// std::string json_result;
+// auto error =  extract_from<"year", "price">(car).get(json_result);
+// if(error) { /* error handling */ }
+```
 
 ### Without `string_buffer` instance but with explicit error handling
 
@@ -194,9 +324,90 @@ pattern:
 
 ```cpp
   std::string json;
-  if(simdjson::builder::to_json_string(c).get(json)) {
+  if(simdjson::to_json(c).get(json)) {
     // there was an error
   } else {
     // json contain the serialized JSON
   }
-```
+```
+
+### Customization
+
+If you want to serialize a value in a custom way, you can do it with a
+`tag_invoke` specialization like the following example which will map
+the year attribute to a string.
+
+
+```cpp
+#include <simdjson>
+
+struct Car {
+  std::string make;
+  std::string model;
+  int64_t year;
+  std::vector<float> tire_pressure;
+};
+
+namespace simdjson {
+
+template <typename builder_type>
+void tag_invoke(serialize_tag, builder_type &builder, const Car& car) {
+  builder.start_object();
+  builder.append_key_value("make", car.make);
+  builder.append_comma();
+  builder.append_key_value("model", car.model);
+  builder.append_comma();
+  builder.append_key_value("year", std::to_string(car.year));
+  builder.append_comma();
+  builder.append_key_value("tire_pressure", car.tire_pressure);
+  builder.end_object();
+}
+
+} // namespace simdjson
+```
+
+### Pretty formatted (fractured JSON)
+
+In some instances, you may want your JSON to be more readable. For this pupose, we also
+support the Fractured JSON standard.
+
+```Cpp
+  TableTestData data{
+    {{1, "Alice", true}, {2, "Bob", false}, {3, "Carol", true}, {4, "Dave", false}}
+  };
+
+  fractured_json_options opts;
+  opts.enable_table_format = true;
+  opts.min_table_rows = 3;
+
+  std::string formatted = simdjson::to_fractured_json_string(data, opts);
+```
+
+The result might be as follows.
+
+```json
+{
+    "records": [
+        { "active": true , "id": 1, "name": "Alice" },
+        { "active": false, "id": 2, "name": "Bob" },
+        { "active": true , "id": 3, "name": "Carol" },
+        { "active": false, "id": 4, "name": "Dave" }
+    ]
+}
+```
+
+The `fractured_json_options` struct allows you to customize the formatting behavior. It includes the following options:
+
+- `max_total_line_length` (default: 120): Maximum total characters per line. Content exceeding this will be expanded to multiple lines.
+- `max_inline_length` (default: 80): Maximum length for inlined elements. Simple arrays/objects shorter than this may be rendered inline.
+- `max_inline_complexity` (default: 2): Maximum nesting depth for inline rendering. Elements with complexity exceeding this will be expanded. Complexity 0 = scalar, 1 = flat array/object, 2 = one level of nesting.
+- `max_compact_array_complexity` (default: 1): Maximum complexity for compact array formatting. Arrays with elements of this complexity or less may have multiple items per line.
+- `indent_spaces` (default: 4): Number of spaces per indentation level.
+- `enable_table_format` (default: true): Enable tabular formatting for arrays of similar objects. When enabled, arrays of objects with identical keys are formatted as aligned tables.
+- `min_table_rows` (default: 3): Minimum number of rows to trigger table mode.
+- `table_similarity_threshold` (default: 0.8): Similarity threshold for table detection. Objects must share at least this fraction of keys to be formatted as a table.
+- `enable_compact_multiline` (default: true): Enable compact multiline arrays. When enabled, arrays of simple elements may have multiple items per line.
+- `max_items_per_line` (default: 10): Maximum array items per line in compact mode.
+- `simple_bracket_padding` (default: true): Add space inside brackets for simple containers. When true: `{ "key": "value" }`, when false: `{"key": "value"}`.
+- `colon_padding` (default: true): Add space after colons. When true: `"key": "value"`, when false: `"key":"value"`.
+- `comma_padding` (default: true): Add space after commas in inline content. When true: `[1, 2, 3]`, when false: `[1,2,3]`.

doc/compile_time.md

@@ -0,0 +1,227 @@
+# Parse json at compile time
+   * [Introduction](#introduction)
+   * [Example](#example)
+   * [Concepts](#concepts)
+   * [Loading from disk](#loading-from-disk)
+   * [Limitations (compile-time errors)](#limitations-compile-time-errors)
+
+
+## Introduction
+In some instances, you may want to configure your software at compile-time with a JSON document.
+Maybe you have a single code base but many different possible configurations, all resulting in
+different software. For example, you might be programming robots, using the same software, but
+different robot configurations.
+
+To achieve the desired result, you have a few options. You may start the software and parser a
+JSON file at runtime. Or you might convert your JSON data into C++ code that you can compile with
+your software.
+
+With C++26, there is another way: parse the JSON file along with your C++ code. In this manner,
+the JSON data becomes native C++ data.
+
+The simdjson library supports parsing JSON documents at compile time if you have C++26 support. To
+activate C++26 reflection support, you can compile
+your code with the `SIMDJSON_STATIC_REFLECTION` macro set:
+
+```cpp
+#define SIMDJSON_STATIC_REFLECTION 1
+//...
+#include "simdjson.h"
+```
+
+The `simdjson::compile_time::parse_json` function parses a JSON document at **compile time** and returns a `constexpr` structure reflecting its content. We support the full range of JSON values, which are mapped to C++ types as in
+the following table.
+
+
+| JSON type      | C++ type                         |
+|----------------|----------------------------------|
+| object         | anonymous struct                 |
+| array          | `std::array<T, N>` (homogeneous) |
+| string         | `const char*` (UTF-8)            |
+| number         | `int64_t`, `uint64_t`, `double`  |
+| `true`/`false` | `bool`                           |
+| `null`         | `std::nullptr_t`                 |
+
+## Example
+
+Suppose you want to parse the following JSON document:
+
+```cpp
+{
+    "port": 8080,
+    "host": "localhost",
+    "debug": true
+}
+```
+
+**Reminder**: In C++, `R"( )"` allows us to write multi-line strings with unescaped quotes.
+
+
+You can do so, at compile-time, as follows:
+
+
+```cpp
+constexpr auto cfg = R"(
+
+{
+    "port": 8080,
+    "host": "localhost",
+    "debug": true
+}
+
+)"_json;
+
+// cfg.port == 8080
+// std::string_view(cfg.host) == "localhost"
+// cfg.debug == true
+```
+
+You can nest objects and arrays:
+
+```cpp
+constexpr auto data = R"(
+
+{
+    "servers": [
+        {"host": "s1", "port": 3000},
+        {"host": "s2", "port": 3001}
+    ]
+}
+
+)"_json;
+
+
+// data.servers.size() == 2
+// std::string_view(data.servers[0].host) == "s1"
+```
+
+Top-level arrays are allowed:
+
+```cpp
+constexpr auto arr = R"(
+
+[1, 2, 3]
+
+)"_json;
+static_assert(arr.size() == 3);
+static_assert(arr[1] == 2);
+```
+
+
+## Concepts
+
+Given that the parsed data is made of structures that depend on the JSON input, you might
+want to check that it conforms to your expectation. You can do so with concepts.
+
+Let us consider this example:
+
+```cpp
+    constexpr auto config = R"(
+
+    [
+      { "name": "Alice", "age": 30 },
+      { "name": "Bob", "age": 25 },
+      { "name": "Charlie", "age": 35 }
+    ]
+
+    )"_json;
+```
+
+You might want to ensure that the result is an array of persons. You can define your
+expectation with concepts like so:
+
+```cpp
+template <typename T>
+concept person = requires(T p) {
+    std::string_view(p.name);  // has name field convertible to string_view
+    p.age;                     // has age field
+    requires std::is_integral_v<decltype(p.age)>;  // age is integral
+};
+
+/**
+ * Concept to validate that a type is an array of person objects
+ */
+template <typename T>
+concept array_of_person = requires(T arr) {
+    arr.size();                    // has size method
+    arr[0];                        // can access elements with []
+    requires person<decltype(arr[0])>;  // elements satisfy person concept
+};
+```
+
+And then a simple static assert with `decltype` is sufficient to check that the expectation is met:
+
+```cpp
+  constexpr auto config = R"(
+
+  [
+    { "name": "Alice", "age": 30 },
+    { "name": "Bob", "age": 25 },
+    { "name": "Charlie", "age": 35 }
+  ]
+
+  )"_json;
+
+
+  // Validate that the array satisfies the array_of_person concept
+  static_assert(array_of_person<decltype(config)>);
+```
+
+
+
+## Loading from disk
+
+In practice, you may have a JSON file, say `json_data` that you want to parse
+at compile time. You may do so as follows.
+
+```c++
+constexpr const char json_data[] = {
+    #embed "test.json"
+    , 0
+};
+
+constexpr auto json = simdjson::compile_time::parse_json<json_data>();
+```
+
+
+## Limitations (compile-time errors)
+
+We have a few limitations which trigger compile-time errors if violated.
+
+
+- Only JSON objects and arrays are supported at the top level (no primitives).
+  We will lift this limitation in the future.
+- Strings are represented using the `const char*` in UTF-8, but they must not
+  contain embedded nulls. We would prefer to represent them as std::string or
+  std::string_view, and hope to do so in the future.
+- Heterogeneous arrays are not supported yet. E.g., you need to have arrays of
+  all integers, or all strings, all floats, all compatible objects, etc.
+  For example, the following is accepted:
+  ```json
+   [
+    { "name": "Alice", "age": 30 },
+    { "name": "Bob", "age": 25 },
+    { "name": "Charlie", "age": 35 }
+  ]
+  ```
+  but the following is not:
+  ```json
+  [
+    { "name": "Alice", "age": 30 },
+    "Just a string",
+    42,
+    { "name": "Charlie", "age": 35 }
+  ]
+  ```
+  We may support heterogeneous arrays in the future with std::variant types.
+- We parse the first JSON document encountered in the string. Trailing
+  characters are ignored. Thus if your JSON begins with {"a":1}, everything
+  after the closing brace is ignored. This limitation will be lifted in the future,
+  reporting an error.
+
+These limitations are safe in the sense that they result in compile-time errors.
+Thus you will not get truncated strings or imprecise floats silently.
+
+
+Although we are committed to maintaining the functionality in the long run, the
+`compile_time::parse_json` function is subject to change.

doc/compile_time_accessors.md

@@ -0,0 +1,445 @@
+# Compile-Time JSONPath and JSON Pointer Accessors
+
+**Note:** This feature requires C++26 Static Reflection support (P2996) and is currently only available with experimental compilers. You must enable it with `-DSIMDJSON_STATIC_REFLECTION=ON` when building.
+
+## Overview
+
+simdjson provides compile-time JSONPath and JSON Pointer accessors that validate paths against struct definitions at compile time and generate optimized accessor code with zero runtime overhead. This combines the safety of compile-time type checking with the performance of pre-parsed, pre-validated access paths.
+
+## Requirements
+
+- C++26 compiler with Static Reflection support (P2996)
+- Experimental compiler flags:
+  - Clang with P2996 support: `-std=c++26 -freflection -fexpansion-statements`
+- Build configuration: `-DSIMDJSON_STATIC_REFLECTION=ON`
+
+## How It Works
+
+**Compile Time:**
+1. Path string is parsed and converted to access steps
+2. Path is validated against struct definition using reflection
+3. Field types are checked and verified
+4. Optimized accessor code is generated
+
+**Runtime:**
+- Direct navigation with no parsing
+- No validation overhead
+- No string comparisons for path components
+- Type-safe extraction
+
+## Two Usage Modes
+
+### Mode 1: With Type Validation (Recommended)
+
+When you provide a struct type, the compiler validates the entire path at compile time:
+
+```cpp
+struct User {
+  std::string name;
+  int age;
+  std::vector<std::string> emails;
+};
+
+//  R"( ... )" is a C++ raw string literal.
+const padded_string json = R"({
+  "name": "Alice",
+  "age": 30,
+  "emails": ["alice@example.com", "alice@work.com"]
+})"_padded;
+
+ondemand::parser parser;
+auto doc = parser.iterate(json);
+
+// Compile-time validation: checks that User has "name" field of type std::string
+std::string name;
+auto result = ondemand::json_path::at_path_compiled<User, ".name">(doc);
+result.get(name); // name = "Alice"
+
+// Compile-time validation: checks that "emails" is array-like with string elements
+std::string email;
+result = ondemand::json_path::at_path_compiled<User, ".emails[0]">(doc);
+result.get(email); // email = "alice@example.com"
+```
+
+**Benefits:**
+- **Compile-time errors** if path doesn't exist in struct
+- **Type safety** - verifies field types match expected types
+- **Refactoring protection** - renaming struct fields causes compile errors
+
+**What gets validated:**
+- Field existence
+- Field types
+- Array/container access validity
+- Nested struct navigation
+
+### Mode 2: Without Validation
+
+When you omit the struct type, the path is parsed at compile time but not validated:
+
+```cpp
+const padded_string json = R"({
+  "name": "Alice",
+  "age": 30,
+  "address": {"city": "Boston"}
+})"_padded;
+
+ondemand::parser parser;
+auto doc = parser.iterate(json);
+
+// No compile-time validation - path is only parsed
+std::string name;
+auto result = ondemand::json_path::at_path_compiled<".name">(doc);
+result.get(name); // name = "Alice"
+
+std::string_view city;
+result = ondemand::json_path::at_path_compiled<".address.city">(doc);
+result.get(city); // city = "Boston"
+```
+
+**Benefits:**
+- Works with dynamic/unknown JSON structures
+- Still benefits from compile-time path parsing
+- No runtime string parsing overhead
+
+**Use when:**
+- JSON structure is not known at compile time
+- Working with varied JSON schemas
+- Prototyping or exploratory parsing
+
+## JSONPath Syntax
+
+JSONPath uses dot notation and bracket notation for field access:
+
+### Supported Syntax
+
+| Syntax | Description | Example |
+|--------|-------------|---------|
+| `.field` | Dot notation for field access | `.name`, `.address.city` |
+| `["field"]` | Bracket notation with quotes | `["name"]`, `["address"]["city"]` |
+| `[index]` | Array index access | `[0]`, `[1]` |
+| Mixed | Combination of notations | `.emails[0]`, `["users"][0].name` |
+| `$` prefix | Optional root indicator | `$.name`, `$["name"]` |
+
+### Examples
+
+```cpp
+struct Address {
+  std::string city;
+  int zip;
+};
+
+struct Person {
+  std::string name;
+  int age;
+  Address address;
+  std::vector<std::string> emails;
+};
+
+// Dot notation
+at_path_compiled<Person, ".name">(doc)
+at_path_compiled<Person, ".address.city">(doc)
+
+// Bracket notation
+at_path_compiled<Person, "[\"name\"]">(doc)
+at_path_compiled<Person, "[\"address\"][\"city\"]">(doc)
+
+// Array access
+at_path_compiled<Person, ".emails[0]">(doc)
+at_path_compiled<Person, ".emails[1]">(doc)
+
+// Mixed notation
+at_path_compiled<Person, ".address[\"zip\"]">(doc)
+at_path_compiled<Person, "[\"emails\"][0]">(doc)
+
+// With root indicator
+at_path_compiled<Person, "$.name">(doc)
+at_path_compiled<Person, "$.address.city">(doc)
+```
+
+## JSON Pointer Syntax
+
+JSON Pointer (RFC 6901) uses slash-separated paths:
+
+### Supported Syntax
+
+| Syntax | Description | Example |
+|--------|-------------|---------|
+| `/field` | Field access | `/name`, `/address/city` |
+| `/index` | Array index | `/0`, `/1` |
+| `~0` | Escaped `~` | `/field~0name` → field~name |
+| `~1` | Escaped `/` | `/field~1name` → field/name |
+
+### Examples
+
+```cpp
+struct Car {
+  std::string make;
+  std::string model;
+  int64_t year;
+  std::vector<double> tire_pressure;
+};
+
+// Field access
+at_pointer_compiled<Car, "/make">(doc)
+at_pointer_compiled<Car, "/model">(doc)
+
+// Array access
+at_pointer_compiled<Car, "/tire_pressure/0">(doc)
+at_pointer_compiled<Car, "/tire_pressure/1">(doc)
+
+// Root pointer (returns whole document)
+at_pointer_compiled<Car, "">(doc)
+at_pointer_compiled<Car, "/">(doc)
+```
+
+## API Reference
+
+### JSONPath Functions
+
+```cpp
+// With type validation
+template<typename T, constevalutil::fixed_string Path, typename DocOrValue>
+simdjson_result<value> at_path_compiled(DocOrValue& doc_or_val);
+
+// Without validation
+template<constevalutil::fixed_string Path, typename DocOrValue>
+simdjson_result<value> at_path_compiled(DocOrValue& doc_or_val);
+```
+
+### JSON Pointer Functions
+
+```cpp
+// With type validation
+template<typename T, constevalutil::fixed_string Pointer, typename DocOrValue>
+simdjson_result<value> at_pointer_compiled(DocOrValue& doc_or_val);
+
+// Without validation
+template<constevalutil::fixed_string Pointer, typename DocOrValue>
+simdjson_result<value> at_pointer_compiled(DocOrValue& doc_or_val);
+```
+
+### Direct Field Extraction
+
+Extract values directly into variables with compile-time type checking:
+
+```cpp
+// JSONPath
+template<typename T, constevalutil::fixed_string Path>
+struct path_accessor {
+  template<typename DocOrValue, typename FieldType>
+  static error_code extract_field(DocOrValue& doc_or_val, FieldType& target);
+};
+
+// JSON Pointer
+template<typename T, constevalutil::fixed_string Pointer>
+struct pointer_accessor {
+  template<typename DocOrValue, typename FieldType>
+  static error_code extract_field(DocOrValue& doc_or_val, FieldType& target);
+};
+```
+
+**Example:**
+
+```cpp
+struct User {
+  std::string name;
+  int age;
+};
+
+ondemand::parser parser;
+auto doc = parser.iterate(json);
+
+// Extract directly into variable
+std::string name;
+ondemand::json_path::path_accessor<User, ".name">::extract_field(doc, name);
+
+int age;
+ondemand::json_path::pointer_accessor<User, "/age">::extract_field(doc, age);
+```
+
+The compiler verifies that the target variable type matches the field type at the path.
+
+## Complete Examples
+
+### Example 1: Validated Access
+
+```cpp
+#include "simdjson.h"
+using namespace simdjson;
+
+struct Car {
+  std::string make;
+  std::string model;
+  int64_t year;
+  std::vector<double> tire_pressure;
+};
+
+int main() {
+  const padded_string json = R"({
+    "make": "Toyota",
+    "model": "Camry",
+    "year": 2018,
+    "tire_pressure": [40.1, 39.9, 37.7, 40.4]
+  })"_padded;
+
+  ondemand::parser parser;
+  auto doc = parser.iterate(json);
+
+  // Type-validated access
+  std::string make;
+  auto result = ondemand::json_path::at_path_compiled<Car, ".make">(doc);
+  result.get(make); // make = "Toyota"
+
+  // Array access with validation
+  double pressure;
+  result = ondemand::json_path::at_path_compiled<Car, ".tire_pressure[1]">(doc);
+  result.get(pressure); // pressure = 39.9
+
+  return 0;
+}
+```
+
+### Example 2: Non-Validated Access
+
+```cpp
+#include "simdjson.h"
+using namespace simdjson;
+
+int main() {
+  const padded_string json = R"({
+    "user": {
+      "name": "Alice",
+      "preferences": {
+        "theme": "dark",
+        "notifications": true
+      }
+    }
+  })"_padded;
+
+  ondemand::parser parser;
+  auto doc = parser.iterate(json);
+
+  // No validation - works with any JSON structure
+  std::string_view theme;
+  auto result = ondemand::json_path::at_path_compiled<".user.preferences.theme">(doc);
+  result.get(theme); // theme = "dark"
+
+  bool notifications;
+  result = ondemand::json_path::at_path_compiled<".user.preferences.notifications">(doc);
+  result.get(notifications); // notifications = true
+
+  return 0;
+}
+```
+
+### Example 3: Direct Extraction
+
+```cpp
+#include "simdjson.h"
+using namespace simdjson;
+
+struct Person {
+  std::string name;
+  int age;
+  std::vector<std::string> emails;
+};
+
+int main() {
+  const padded_string json = R"({
+    "name": "Bob",
+    "age": 25,
+    "emails": ["bob@example.com", "bob@work.com"]
+  })"_padded;
+
+  ondemand::parser parser;
+  auto doc = parser.iterate(json);
+
+  // Extract with type validation
+  std::string name;
+  ondemand::json_path::path_accessor<Person, ".name">::extract_field(doc, name);
+  // name = "Bob"
+
+  int age;
+  ondemand::json_path::pointer_accessor<Person, "/age">::extract_field(doc, age);
+  // age = 25
+
+  std::string email;
+  ondemand::json_path::path_accessor<Person, ".emails[0]">::extract_field(doc, email);
+  // email = "bob@example.com"
+
+  return 0;
+}
+```
+
+## Error Handling
+
+Compile-time errors occur when:
+- Path doesn't exist in struct: `static_assert` failure
+- Field type mismatch: `static_assert` failure
+- Invalid array access on non-array field: `static_assert` failure
+
+Runtime errors occur when:
+- JSON structure doesn't match expected structure
+- Array index out of bounds
+- Type conversion failures
+
+```cpp
+struct User {
+  std::string name;
+  int age;
+};
+
+// Compile-time error: no "email" field in User
+// auto result = ondemand::json_path::at_path_compiled<User, ".email">(doc);
+
+// Compile-time error: age is not an array
+// auto result = ondemand::json_path::at_path_compiled<User, ".age[0]">(doc);
+
+// Runtime error if JSON doesn't have "name" field
+auto result = ondemand::json_path::at_path_compiled<User, ".name">(doc);
+std::string name;
+if (result.get(name) != SUCCESS) {
+  // Handle error
+}
+```
+
+## Performance
+
+Compile-time accessors provide:
+- **Zero path parsing overhead** - paths parsed at compile time
+- **Zero validation overhead** - validation done at compile time
+- **Direct field access** - no runtime path traversal
+- **Type-safe extraction** - no dynamic type checking
+
+Compared to runtime `at_path()` and `at_pointer()`:
+- Eliminates runtime path string parsing
+- Eliminates runtime path validation
+- Generates optimal code path directly
+
+## Limitations
+
+- Requires C++26 compiler with P2996 support (experimental)
+- Paths must be compile-time constants (string literals)
+- Cannot use runtime-computed paths
+- Limited to struct types that support reflection
+- Array indices must be compile-time constants in the path
+
+## When to Use
+
+**Use compile-time accessors when:**
+- You have well-defined struct types
+- JSON structure is known at compile time
+- You want maximum type safety
+- Performance is critical
+
+**Use runtime `at_path()`/`at_pointer()` when:**
+- JSON structure varies or is unknown
+- Paths are computed at runtime
+- Working with C++20 or earlier
+- Flexibility is more important than compile-time checks
+
+## See Also
+
+- [JSON Pointer](basics.md#json-pointer) - Runtime JSON Pointer support
+- [JSONPath](basics.md#jsonpath) - Runtime JSONPath support
+- [Static Reflection for Deserialization](basics.md#3-using-static-reflection-c26) - Using reflection for full struct deserialization

doc/dom.md

@@ -41,7 +41,7 @@ The Basics: Loading and Parsing JSON Documents using the DOM front-end
 The simdjson library offers a simple DOM tree API, which you can access by creating a
 `dom::parser` and calling the `load()` method:
 
-```c++
+```cpp
 dom::parser parser;
 dom::element doc = parser.load(filename); // load and parse a file
 ```
@@ -49,21 +49,39 @@ dom::element doc = parser.load(filename); // load and parse a file
 Or by creating a padded string (for efficiency reasons, simdjson requires a string with
 SIMDJSON_PADDING bytes at the end) and calling `parse()`:
 
-```c++
+```cpp
 dom::parser parser;
 dom::element doc = parser.parse("[1,2,3]"_padded); // parse a string, the _padded suffix creates a simdjson::padded_string instance
 ```
 
+You can also load a `padded_string` from a file.
+
+
+```cpp
+auto json = padded_string::load("twitter.json"); // load JSON file 'twitter.json'.
+dom::element doc = parser.parse(json);
+```
+
+[You can similarly fetch a file from a URL to a padded string](https://github.com/simdjson/curltostring) using our `simdjson::padded_string_builder`.
+
+(Windows users compiling with C++17 or better may use `wchar_t` strings to support non-ASCII
+filenames: `padded_string::load(L"twitter.json")`.)
+
+
+(Windows users compiling with C++17 or better may use `wchar_t` strings to support non-ASCII
+filenames: `padded_string::load(L"twitter.json")`.)
+
+
 You can copy your data directly on a `simdjson::padded_string` as follows:
 
-```c++
+```cpp
 const char * data = "my data"; // 7 bytes
 simdjson::padded_string my_padded_data(data, 7); // copies to a padded buffer
 ```
 
 Or as follows...
 
-```c++
+```cpp
 std::string data = "my data";
 simdjson::padded_string my_padded_data(data); // copies to a padded buffer
 ```
@@ -83,7 +101,7 @@ container-overflow checks, you may encounter sanitizer warnings.
 You can safely ignore these warnings. Or you can call `simdjson::pad(std::string&)` to pad the
 string with `SIMDJSON_PADDING` spaces: this function returns a `simdjson::padding_string_view` which can be be passed to the parser's iterator function:
 
-```c++
+```cpp
 std::string json = "[1]";
 dom::element doc = parser.parse(simdjson::pad(json));
 ```
@@ -117,8 +135,9 @@ Once you have an element, you can navigate it with idiomatic C++ iterators, oper
   dom::object and dom::array. An exception (`simdjson::simdjson_error`) is thrown if the cast is not possible.
 * **Extracting Values (without exceptions):** You can use a variant usage of `get()` with error codes to avoid exceptions. You first declare the variable of the appropriate type (`double`, `uint64_t`, `int64_t`, `bool`, `std::string_view`,
   `dom::object` and `dom::array`) and pass it by reference to `get()` which gives you back an error code: e.g.,
-  ```c++
+  ```cpp
   simdjson::error_code error;
+  // _padded returns an simdjson::padded_string instance
   simdjson::padded_string numberstring = "1.2"_padded; // our JSON input ("1.2")
   simdjson::dom::parser parser;
   double value; // variable where we store the value to be parsed
@@ -129,7 +148,7 @@ Once you have an element, you can navigate it with idiomatic C++ iterators, oper
   The strings contain unescaped valid UTF-8 strings: no unmatched surrogate is allowed.
   Internally, numbers are stored as either 64-bit integers or 64-bit floating-point numbers.
   Thus it is possible to get the full 64-bit integer range (either signed or  unsigned).
-  By default, the string `-0` is parsed as the integer 0 as in Pytho or C++. If you set the macro
+  By default, the string `-0` is parsed as the integer 0 as in Python or C++. If you set the macro
   `SIMDJSON_MINUS_ZERO_AS_FLOAT` to `1` when building simdjson, you can get that `-0` is mapped to `-0.0`
   as in JavaScript. You can get the desired effect by building simdjson with cmake setting the
   `SIMDJSON_MINUS_ZERO_AS_FLOAT` to on: `cmake -B build -D SIMDJSON_MINUS_ZERO_AS_FLOAT=ON`.
@@ -152,7 +171,8 @@ Once you have an element, you can navigate it with idiomatic C++ iterators, oper
 
 The following code illustrates all of the above:
 
-```c++
+```cpp
+//  R"( ... )" is a C++ raw string literal.
 auto cars_json = R"( [
   { "make": "Toyota", "model": "Camry",  "year": 2018, "tire_pressure": [ 40.1, 39.9, 37.7, 40.4 ] },
   { "make": "Kia",    "model": "Soul",   "year": 2012, "tire_pressure": [ 30.1, 31.0, 28.6, 28.7 ] },
@@ -185,7 +205,7 @@ for (dom::object car : parser.parse(cars_json)) {
 
 Here is a different example illustrating the same ideas:
 
-```C++
+```cpp
 auto abstract_json = R"( [
     {  "12345" : {"a":12.34, "b":56.78, "c": 9998877}   },
     {  "12545" : {"a":11.44, "b":12.78, "c": 11111111}  }
@@ -207,7 +227,7 @@ for (dom::object obj : parser.parse(abstract_json)) {
 And another one:
 
 
-```C++
+```cpp
   auto abstract_json = R"(
     {  "str" : { "123" : {"abc" : 3.14 } } } )"_padded;
   dom::parser parser;
@@ -221,7 +241,7 @@ C++17 Support
 
 While the simdjson library can be used in any project using C++ 11 and above, field iteration has special support C++ 17's destructuring syntax. For example:
 
-```c++
+```cpp
 padded_string json = R"(  { "foo": 1, "bar": 2 }  )"_padded;
 dom::parser parser;
 dom::object object; // invalid until the get() succeeds
@@ -234,7 +254,7 @@ for (auto [key, value] : object) {
 
 For comparison, here is the C++ 11 version of the same code:
 
-```c++
+```cpp
 // C++ 11 version for comparison
 padded_string json = R"(  { "foo": 1, "bar": 2 }  )"_padded;
 dom::parser parser;
@@ -251,7 +271,7 @@ C++20 Support
 
 simdjson library also supports some C++20 feature including `std::ranges`:
 
-```c++
+```cpp
 auto cars_json = R"( [
   { "make": "Toyota", "model": "Camry",  "year": 2018, "tire_pressure": [ 40.1, 39.9, 37.7, 40.4 ] },
   { "make": "Kia",    "model": "Soul",   "year": 2012, "tire_pressure": [ 30.1, 31.0, 28.6, 28.7 ] },
@@ -270,7 +290,7 @@ JSON Pointer
 The simdjson library also supports [JSON pointer](https://tools.ietf.org/html/rfc6901) through the
 `at_pointer()` method, letting you reach further down into the document in a single call:
 
-```c++
+```cpp
 auto cars_json = R"( [
   { "make": "Toyota", "model": "Camry",  "year": 2018, "tire_pressure": [ 40.1, 39.9, 37.7, 40.4 ] },
   { "make": "Kia",    "model": "Soul",   "year": 2012, "tire_pressure": [ 30.1, 31.0, 28.6, 28.7 ] },
@@ -291,7 +311,7 @@ You can apply a JSON Pointer expression to any node and the path gets interprete
 
 Consider the following example:
 
-```c++
+```cpp
 auto cars_json = R"( [
   { "make": "Toyota", "model": "Camry",  "year": 2018, "tire_pressure": [ 40.1, 39.9, 37.7, 40.4 ] },
   { "make": "Kia",    "model": "Soul",   "year": 2012, "tire_pressure": [ 30.1, 31.0, 28.6, 28.7 ] },
@@ -313,11 +333,11 @@ JSONPath
 ------------
 
 
-The simdjson library supports a subset of [JSONPath](https://datatracker.ietf.org/doc/html/draft-normington-jsonpath-00) through the `at_path()` method, allowing you to reach further into the document in a single call. The subset of JSONPath that is implemented is the subset that is trivially convertible into the JSON Pointer format, using `.` to access a field and `[]` to access a specific index.
+The simdjson library supports a subset of [JSONPath](https://www.rfc-editor.org/rfc/rfc9535) (RFC 9535) through the `at_path()` method, allowing you to reach further into the document in a single call. The subset of JSONPath that is implemented is the subset that is trivially convertible into the JSON Pointer format, using `.` to access a field and `[]` to access a specific index.
 
 Consider the following example:
 
-```c++
+```cpp
 auto cars_json = R"( [
   { "make": "Toyota", "model": "Camry",  "year": 2018, "tire_pressure": [ 40.1, 39.9, 37.7, 40.4 ] },
   { "make": "Kia",    "model": "Soul",   "year": 2012, "tire_pressure": [ 30.1, 31.0, 28.6, 28.7 ] },
@@ -336,7 +356,7 @@ cout << p << endl; // Prints 39.9
 
 We also support the `$` prefix. When you start a JSONPath expression with $, you are indicating that the path starts from the root of the JSON document. E.g.,
 
-```c++
+```cpp
 auto json = R"( { "c" :{ "foo": { "a": [ 10, 20, 30 ] }}, "d": { "foo2": { "a": [ 10, 20, 30 ] }} , "e": 120 })"_padded;
 dom::parser parser;
 dom::element doc;
@@ -354,13 +374,81 @@ if(error) { /*won't happen*/ }
 ```
 
 
+## Using `at_path_with_wildcard` for JSONPath Queries
+
+The `at_path_with_wildcard` function in simdjson extends the JSONPath querying capabilities by supporting wildcard expressions (`*`) in JSON paths. This allows users to retrieve multiple elements from a JSON document in a single query. For example, you can use `$.address.*` to fetch all fields within the `address` object or `$.phoneNumbers[*].numbers[*]` to retrieve all phone numbers across multiple objects in an array.
+
+The `*` wildcard matches all elements at a specific level. For instance, `$.address.*` retrieves all key-value pairs in the `address` object, while `$.*.streetAddress` fetches all `streetAddress` fields across objects at the root level.  You can combine wildcards with array indexing. For example, `$.phoneNumbers[*].numbers[1]` retrieves the second number from each `numbers` array in the `phoneNumbers` array. If no elements match the wildcard query, the function returns an empty result. For instance, querying `$.empty_object.*` or `$.empty_array.*` will yield an empty set.
+
+### Example Usage
+
+Here is an example demonstrating the use of `at_path_with_wildcard`:
+
+```cpp
+simdjson::padded_string json_string = R"(
+{
+  "firstName": "John",
+  "lastName": "doe",
+  "age": 26,
+  "address": {
+    "streetAddress": "naist street",
+    "city": "Nara",
+    "postalCode": "630-0192"
+  },
+  "phoneNumbers": [
+    {
+      "type": "iPhone",
+      "numbers": ["0123-4567-8888", "0123-4567-8788"]
+    },
+    {
+      "type": "home",
+      "numbers": ["0123-4567-8910"]
+    }
+  ]
+})"_padded;
+
+dom::parser parser;
+dom::element parsed_json = parser.parse(json_string);
+std::vector<dom::element> values;
+
+// Fetch all fields in the address object
+auto error = parsed_json.at_path_with_wildcard("$.address.*").get(values);
+if(error) {
+  // do something
+}
+for (auto &value : values) {
+  std::string_view field;
+  error = value.get(field);
+  if(error) {
+    // do something
+  }
+  std::cout << field << std::endl;
+}
+
+// Fetch all phone numbers
+error = parsed_json.at_path_with_wildcard("$.phoneNumbers[*].numbers[*]").get(values);
+if(error) {
+  // do something
+}
+for (auto &value : values) {
+  std::string_view number;
+  error = value.get(number);
+  if(error) {
+    // do something
+  }
+  std::cout << number << std::endl;
+}
+```
+
+This function is particularly useful for extracting data from complex JSON structures with nested arrays and objects. By leveraging wildcards, you can simplify your queries and reduce the need for multiple iterations.
+
 Error Handling
 --------------
 
 All simdjson APIs that can fail return `simdjson_result<T>`, which is a &lt;value, error_code&gt;
 pair. You can retrieve the value with .get(), like so:
 
-```c++
+```cpp
 dom::element doc;
 auto error = parser.parse(json).get(doc);
 if (error) { cerr << error << endl; exit(1); }
@@ -394,7 +482,7 @@ We can write a "quick start" example where we attempt to parse the following JSO
 Our program loads the file, selects value corresponding to key "search_metadata" which expected to be an object, and then
 it selects the key "count" within that object.
 
-```C++
+```cpp
 #include <iostream>
 #include "simdjson.h"
 
@@ -422,7 +510,7 @@ triggering exceptions. To do this, we use `["statuses"].at(0)["id"]`. We break t
 
 Observe how we use the `at` method when querying an index into an array, and not the bracket operator.
 
-```C++
+```cpp
 #include <iostream>
 #include "simdjson.h"
 
@@ -446,7 +534,7 @@ over the content of an array.
 
 This is how the example in "Using the Parsed JSON" could be written using only error code checking:
 
-```c++
+```cpp
 auto cars_json = R"( [
   { "make": "Toyota", "model": "Camry",  "year": 2018, "tire_pressure": [ 40.1, 39.9, 37.7, 40.4 ] },
   { "make": "Kia",    "model": "Soul",   "year": 2012, "tire_pressure": [ 30.1, 31.0, 28.6, 28.7 ] },
@@ -493,7 +581,7 @@ for (dom::element car_element : cars) {
 
 Here is another example:
 
-```C++
+```cpp
 auto abstract_json = R"( [
     {  "12345" : {"a":12.34, "b":56.78, "c": 9998877}   },
     {  "12545" : {"a":11.44, "b":12.78, "c": 11111111}  }
@@ -526,7 +614,7 @@ for (dom::element elem : array) {
 
 And another one:
 
-```C++
+```cpp
   auto abstract_json = R"(
     {  "str" : { "123" : {"abc" : 3.14 } } } )"_padded;
   dom::parser parser;
@@ -540,7 +628,7 @@ Notice how we can string several operations (`parser.parse(abstract_json)["str"]
 
 The next two functions will take as input a JSON document containing an array with a single element, either a string or a number. They return true upon success.
 
-```C++
+```cpp
 simdjson::dom::parser parser{};
 
 bool parse_double(const char *j, double &d) {
@@ -572,7 +660,7 @@ target_compile_definitions(simdjson PUBLIC SIMDJSON_EXCEPTIONS=OFF)
 
 Users more comfortable with an exception flow may choose to directly cast the `simdjson_result<T>` to the desired type:
 
-```c++
+```cpp
 dom::element doc = parser.parse(json); // Throws an exception if there was an error!
 ```
 
@@ -582,7 +670,7 @@ program from continuing if there was an error.
 
 If one is willing to trigger exceptions, it is possible to write simpler code:
 
-```C++
+```cpp
 #include <iostream>
 #include "simdjson.h"
 
@@ -603,7 +691,7 @@ inspect or walk over JSON elements. To do that, you can use iterators and the ty
 example, here's a quick and dirty recursive function that verbosely prints the JSON document as JSON
 (* ignoring nuances like trailing commas and escaping strings, for brevity's sake):
 
-```c++
+```cpp
 void print_json(dom::element element) {
   switch (element.type()) {
     case dom::element_type::ARRAY:
@@ -659,7 +747,7 @@ and reuse it. The simdjson library will allocate and retain internal buffers bet
 buffers hot in cache and keeping memory allocation and initialization to a minimum. In this manner,
 you can parse terabytes of JSON data without doing any new allocation.
 
-```c++
+```cpp
 dom::parser parser;
 
 // This initializes buffers and a document big enough to handle this JSON.
@@ -702,7 +790,7 @@ without bound:
 
 * You can set a *max capacity* when constructing a parser:
 
-  ```c++
+  ```cpp
   dom::parser parser(1000*1000); // Never grow past documents > 1MB
   for (web_request request : listen()) {
     dom::element doc;
@@ -718,7 +806,7 @@ without bound:
 * You can set a *fixed capacity* that never grows, as well, which can be excellent for
   predictability and reliability, since simdjson will never call malloc after startup!
 
-  ```c++
+  ```cpp
   dom::parser parser(0); // This parser will refuse to automatically grow capacity
   auto error = parser.allocate(1000*1000); // This allocates enough capacity to handle documents <= 1MB
   if (error) { cerr << error << endl; exit(1); }
@@ -749,7 +837,7 @@ When calling `parser.parse` on a pointer (e.g., `parser.parse(my_char_pointer, m
 Some users may not be able use our `padded_string` class or to load the data directly from disk (`parser.load`). They may need to pass data pointers to the library.  If these users wish to avoid temporary copies and corresponding temporary memory allocations, they may want to call `parser.parse` with the `realloc_if_needed` parameter set to false (e.g., `parser.parse(my_char_pointer, my_length_in_bytes, false)`). In such cases, they need to ensure that there are at least SIMDJSON_PADDING extra bytes at the end that can be safely accessed and read. They do not need to initialize the padded bytes to any value in particular. The following example is safe:
 
 
-```C++
+```cpp
 const char *json      = R"({"key":"value"})";
 const size_t json_len = std::strlen(json);
 std::unique_ptr<char[]> padded_json_copy{new char[json_len + SIMDJSON_PADDING]};
@@ -757,7 +845,7 @@ memcpy(padded_json_copy.get(), json, json_len);
 memset(padded_json_copy.get() + json_len, 0, SIMDJSON_PADDING);
 simdjson::dom::parser parser;
 simdjson::dom::element element = parser.parse(padded_json_copy.get(), json_len, false);
-````
+```
 
 Setting the `realloc_if_needed` parameter `false` in this manner may lead to better performance since copies are avoided, but it requires that the user takes more responsibilities: the simdjson library cannot verify that the input buffer was padded with SIMDJSON_PADDING extra bytes.
 

doc/implementation-selection.md

@@ -55,7 +55,7 @@ Inspecting the Detected Implementation
 
 You can check what implementation is running with `active_implementation`:
 
-```c++
+```cpp
 cout << "simdjson v" << SIMDJSON_VERSION << endl;
 cout << "Detected the best implementation for your machine: " << simdjson::get_active_implementation()->name();
 cout << "(" << simdjson::get_active_implementation()->description() << ")" << endl;
@@ -68,7 +68,7 @@ Querying Available Implementations
 
 You can list all available implementations, regardless of which one was selected:
 
-```c++
+```cpp
 for (auto implementation : simdjson::get_available_implementations()) {
   cout << implementation->name() << ": " << implementation->description() << endl;
 }
@@ -76,7 +76,7 @@ for (auto implementation : simdjson::get_available_implementations()) {
 
 And look them up by name:
 
-```c++
+```cpp
 cout << simdjson::get_available_implementations()["fallback"]->description() << endl;
 ```
 When an implementation is not available, the bracket call `simdjson::get_available_implementations()[name]`
@@ -93,7 +93,7 @@ Manually Selecting the Implementation
 If you're trying to do performance tests or see how different implementations of simdjson run, you
 can select the CPU architecture yourself:
 
-```c++
+```cpp
 // Use the fallback implementation, even though my machine is fast enough for anything
 simdjson::get_active_implementation() = simdjson::get_available_implementations()["fallback"];
 ```
@@ -102,7 +102,7 @@ You are responsible for ensuring that the requirements of the selected implement
 Furthermore, you should check that the implementation is available before setting it to `simdjson::get_active_implementation()`
 by comparing it with the null pointer.
 
-```c++
+```cpp
 auto my_implementation = simdjson::get_available_implementations()["haswell"];
 if (! my_implementation) { exit(1); }
 if (! my_implementation->supported_by_runtime_system()) { exit(1); }
@@ -114,7 +114,7 @@ Checking that an Implementation can Run on your System
 
 You should call `supported_by_runtime_system()` to compare the processor's features with the need of the implementation.
 
-```c++
+```cpp
 for (auto implementation : simdjson::get_available_implementations()) {
   if (implementation->supported_by_runtime_system()) {
     cout << implementation->name() << ": " << implementation->description() << endl;

doc/iterate_many.md

@@ -8,7 +8,7 @@ library provides high-speed access to files or streams containing multiple small
 {"text":"a"}
 {"text":"b"}
 {"text":"c"}
-...
+"..."
 ```
 ... you want to read the entries (individual JSON documents) as quickly and as conveniently as possible. Importantly, the input might span several gigabytes, but you want to use a small (fixed) amount of memory. Ideally, you'd also like the parallelize the processing (using more than one core) to speed up the process.
 
@@ -132,7 +132,7 @@ E.g., `[1,2]{"32":1}` is recognized as two documents.
 Some official formats **(non-exhaustive list)**:
 - [Newline-Delimited JSON (NDJSON)](https://github.com/ndjson/ndjson-spec/)
 - [JSON lines (JSONL)](http://jsonlines.org/)
-- [Record separator-delimited JSON (RFC 7464)](https://tools.ietf.org/html/rfc7464) <- Not supported by JsonStream!
+- [Record separator-delimited JSON (RFC 7464)](https://tools.ietf.org/html/rfc7464) <- Not supported by simdjson!
 - [More on Wikipedia...](https://en.wikipedia.org/wiki/JSON_streaming)
 
 API
@@ -140,8 +140,10 @@ API
 
 Example:
 
-```c++
+```cpp
+//  R"( ... )" is a C++ raw string literal.
 auto json = R"({ "foo": 1 } { "foo": 2 } { "foo": 3 } )"_padded;
+// _padded returns an simdjson::padded_string instance
 ondemand::parser parser;
 ondemand::document_stream docs = parser.iterate_many(json);
 for (auto doc : docs) {
@@ -197,7 +199,7 @@ and `error()` to check if there were any error.
 Let us illustrate the idea with code:
 
 
-```C++
+```cpp
     auto json = R"([1,2,3]  {"1":1,"2":3,"4":4} [1,2,3]  )"_padded;
     simdjson::ondemand::parser parser;
     simdjson::ondemand::document_stream stream;
@@ -238,7 +240,7 @@ Some users may need to work with truncated streams. The simdjson may truncate do
 
 Consider the following example where a truncated document (`{"key":"intentionally unclosed string  `) containing 39 bytes has been left within the stream. In such cases, the first two whole documents are parsed and returned, and the `truncated_bytes()` method returns 39.
 
-```C++
+```cpp
     auto json = R"([1,2,3]  {"1":1,"2":3,"4":4} {"key":"intentionally unclosed string  )"_padded;
     simdjson::ondemand::parser parser;
     simdjson::ondemand::document_stream stream;
@@ -267,7 +269,7 @@ is effectively ignored, as it is set to at least the document size.
 
 Example:
 
-```C++
+```cpp
     auto json = R"( 1, 2, 3, 4, "a", "b", "c", {"hello": "world"} , [1, 2, 3])"_padded;
     ondemand::parser parser;
     ondemand::document_stream doc_stream;
@@ -309,12 +311,12 @@ The first argument is usually a tag type (often an empty struct) that uniquely i
 
 
 You can deserialize you own data structures conveniently if your system supports C++20.
-When it is the case, the macro `SIMDJSON_SUPPORTS_DESERIALIZATION` will be set to 1 by
+When it is the case, the macro `SIMDJSON_SUPPORTS_CONCEPTS` will be set to 1 by
 the simdjson library.
 
 Consider a custom class `Car`:
 
-```C++
+```cpp
 struct Car {
   std::string make;
   std::string model;
@@ -328,7 +330,7 @@ You may support deserializing directly from a JSON value or document to your own
 by defining a single `tag_invoke` function:
 
 
-```C++
+```cpp
 namespace simdjson {
 // This tag_invoke MUST be inside simdjson namespace
 template <typename simdjson_value>
@@ -370,7 +372,7 @@ tag_invoke functions.
 Given a stream of JSON documents, you can add them to a data structure
 such as a `std::vector<Car>` like so if you support exceptions:
 
-```C++
+```cpp
   padded_string json =
       R"( { "make": "Toyota", "model": "Camry",  "year": 2018,
        "tire_pressure": [ 40.1, 39.9 ] }
@@ -391,7 +393,7 @@ such as a `std::vector<Car>` like so if you support exceptions:
 Otherwise you may use this longer version for explicit handling of errors:
 
 
-```C++
+```cpp
   std::vector<Car> cars;
   for(auto doc : stream) {
     Car c;
@@ -401,4 +403,4 @@ Otherwise you may use this longer version for explicit handling of errors:
     }
     cars.push_back(c);
   }
-```
+```

doc/ondemand_design.md

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

doc/parse_many.md

@@ -132,7 +132,7 @@ Whitespace Characters:
 Some official formats **(non-exhaustive list)**:
 - [Newline-Delimited JSON (NDJSON)](https://github.com/ndjson/ndjson-spec)
 - [JSON lines (JSONL)](http://jsonlines.org/)
-- [Record separator-delimited JSON (RFC 7464)](https://tools.ietf.org/html/rfc7464) <- Not supported by JsonStream!
+- [Record separator-delimited JSON (RFC 7464)](https://tools.ietf.org/html/rfc7464) <- Not supported by simdjson!
 - [More on Wikipedia...](https://en.wikipedia.org/wiki/JSON_streaming)
 
 API
@@ -184,7 +184,7 @@ You may also call the `source()` method to get a `std::string_view` instance on
 Let us illustrate the idea with code:
 
 
-```C++
+```cpp
     auto json = R"([1,2,3]  {"1":1,"2":3,"4":4} [1,2,3]  )"_padded;
     simdjson::dom::parser parser;
     simdjson::dom::document_stream stream;
@@ -225,7 +225,7 @@ Some users may need to work with truncated streams. The simdjson may truncate do
 
 Consider the following example where a truncated document (`{"key":"intentionally unclosed string  `) containing 39 bytes has been left within the stream. In such cases, the first two whole documents are parsed and returned, and the `truncated_bytes()` method returns 39.
 
-```C++
+```cpp
     auto json = R"([1,2,3]  {"1":1,"2":3,"4":4} {"key":"intentionally unclosed string  )"_padded;
     simdjson::dom::parser parser;
     simdjson::dom::document_stream stream;

doc/performance.md

@@ -47,7 +47,7 @@ and reuse it. The simdjson library will allocate and retain internal buffers bet
 buffers hot in cache and keeping memory allocation and initialization to a minimum. In this manner,
 you can parse terabytes of JSON data without doing any new allocation.
 
-```c++
+```cpp
 ondemand::parser parser;
 
 // This initializes buffers  big enough to handle this JSON.
@@ -71,14 +71,14 @@ Reusing string buffers
 
 We recommend against creating many `std::string` or `simdjson::padded_string` instances to store the JSON content in your application. [Creating many non-trivial objects is convenient but often surprisingly slow](https://lemire.me/blog/2020/08/08/performance-tip-constructing-many-non-trivial-objects-is-slow/). Instead, as much as possible, you should allocate (once or a few times) reusable memory buffers where you write your JSON content. If you have a buffer `json_str` (of type `char*`) allocated for  `capacity` bytes and you store a JSON document spanning `length` bytes, you can pass it to simdjson as follows:
 
-```c++
+```cpp
  auto doc = parser.iterate(padded_string_view(json_str, length, capacity));
 ```
 
 or simply
 
 
-```c++
+```cpp
  auto doc = parser.iterate(json_str, length, capacity);
 ```
 
@@ -89,7 +89,7 @@ Server Loops: Long-Running Processes and Memory Capacity
 The On-Demand approach also automatically expands its memory capacity when larger documents are parsed. However, for longer processes where very large files are processed (such as server loops), this capacity is not resized down. On-Demand also lets you adjust the maximal capacity that the parser can process:
 
 * You can set an upper bound (*max_capacity*) when construction the parser:
-```C++
+```cpp
     ondemand::parser parser(1000*1000);  // Never grows past documents > 1 MB
     auto doc = parser.iterate(json);
     for (web_request request : listen()) {
@@ -105,7 +105,7 @@ The On-Demand approach also automatically expands its memory capacity when large
 The capacity will grow as the parser encounters larger documents up to 1 MB.
 
 * You can also allocate a *fixed capacity* that will never grow:
-```C++
+```cpp
     ondemand::parser parser(1000*1000);
     parser.allocate(1000*1000)  // Fix the capacity to 1 MB
     auto doc = parser.iterate(json);
@@ -173,8 +173,6 @@ Recent versions of Microsoft Visual Studio on Windows provides support for the L
 
 We recommend Visual Studio users prefer LLVM (clang-cl). It compiles to faster release binaries. Furthermore, it compilers faster in release mode.
 
-Under Windows, we also support the GNU GCC compiler via MSYS2. The performance of 64-bit MSYS2 under Windows is excellent (on par with Linux).
-
 
 Power Usage and Downclocking
 --------------
@@ -255,7 +253,7 @@ long page_size() {
 // page boundary.
 bool need_allocation(const char *buf, size_t len) {
   return ((reinterpret_cast<uintptr_t>(buf + len - 1) % page_size())
-    + simdjson::SIMDJSON_PADDING > static_cast<uintptr_t>(page_size()));
+    + simdjson::SIMDJSON_PADDING >= static_cast<uintptr_t>(page_size()));
 }
 
 simdjson::padded_string_view
@@ -299,4 +297,62 @@ int main() {
   }
   return EXIT_SUCCESS;
 }
+```
+
+Further, whenever you allocate N bytes, memory allocators tend to allocate more memory, without you necessarily knowing about it. Under linux, you can use the `malloc_usable_size` function to see how much memory was actually allocated.
+Under an Apple plateform, you can  `malloc_size`. The following program illustrates the usage.
+
+```cpp
+#include <iostream>
+#include <cstddef>
+#include <memory>
+#include <cstdlib>
+#ifdef __APPLE__
+#include <malloc/malloc.h>  // for malloc_size on macOS
+#endif
+#ifdef __linux__
+#include <malloc.h> // for malloc_usable_size on Linux
+#endif
+size_t get_usable_size(void* ptr) {
+#ifdef __linux__
+    return malloc_usable_size(ptr);
+#elif defined(__APPLE__)
+    return malloc_size(ptr);
+#else
+    return 0;  // Unsupported platform
+#endif
+}
+
+int main() {
+    std::cout << "Demonstrating allocation overhead and rounding with operator new\n\n";
+
+#ifdef __linux__
+    std::cout << "Platform: Linux\n";
+#elif defined(__APPLE__)
+    std::cout << "Platform: macOS (using malloc_size)\n";
+#else
+    std::cout << "Platform: Other/unsupported (usable size will show 0)\n";
+#endif
+
+    std::cout << "Requested size | Actual usable size\n";
+    std::cout << "---------------|-------------------\n";
+    size_t total_requested = 0;
+    size_t total_usable = 0;
+    for (size_t requested = 1; requested <= 4096; requested++) {
+        total_requested += requested;
+        std::unique_ptr<char[]> ptr(new char[requested]);  // Allocate
+        size_t usable = get_usable_size(ptr.get());  // Get usable size
+        total_usable += usable;
+
+        std::cout << requested << "\t       | " << usable << "\n";
+    }
+    std::cout << "---------------|-------------------\n";
+    std::cout << "Total requested: " << total_requested << " bytes\n";
+    std::cout << "Total usable:    " << total_usable << " bytes\n";
+    std::cout << "Total overhead:  " << (total_usable - total_requested) << " bytes\n";
+    std::cout << "Percentage overhead: "
+              << ((total_usable - total_requested) * 100.0 / total_requested) << " %\n";
+
+    return EXIT_SUCCESS;
+}
 ```

fuzz/fuzz_minify.cpp

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

fuzz/ossfuzz.sh

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

include/simdjson.h

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

include/simdjson/arm64/builder.h

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

include/simdjson/arm64/stringparsing_defs.h

@@ -17,7 +17,8 @@ using namespace simd;
 struct backslash_and_quote {
 public:
   static constexpr uint32_t BYTES_PROCESSED = 32;
-  simdjson_inline static backslash_and_quote copy_and_find(const uint8_t *src, uint8_t *dst);
+  // We only copy if dst is non-null.
+  simdjson_inline backslash_and_quote copy_and_find(const uint8_t *src, uint8_t *dst);
 
   simdjson_inline bool has_quote_first() { return ((bs_bits - 1) & quote_bits) != 0; }
   simdjson_inline bool has_backslash() { return bs_bits != 0; }
@@ -34,8 +35,10 @@ simdjson_inline backslash_and_quote backslash_and_quote::copy_and_find(const uin
   static_assert(SIMDJSON_PADDING >= (BYTES_PROCESSED - 1), "backslash and quote finder must process fewer than SIMDJSON_PADDING bytes");
   simd8<uint8_t> v0(src);
   simd8<uint8_t> v1(src + sizeof(v0));
-  v0.store(dst);
+  if(dst != nullptr) {
-  v1.store(dst + sizeof(v0));
+    v0.store(dst);
+    v1.store(dst + sizeof(v0));
+  }
 
   // Getting a 64-bit bitmask is much cheaper than multiple 16-bit bitmasks on ARM; therefore, we
   // smash them together into a 64-byte mask and get the bitmask from there.

include/simdjson/base.h

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

include/simdjson/builder.h

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

include/simdjson/builtin.h

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

include/simdjson/builtin/builder.h

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

include/simdjson/common_defs.h

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

include/simdjson/compile_time_json.h

@@ -0,0 +1,75 @@
+/**
+ * @file compile_time_json.h
+ * @brief Compile-time JSON parsing using C++26 reflection with
+ * std::meta::substitute()
+ */
+
+#ifndef SIMDJSON_GENERIC_COMPILE_TIME_JSON_H
+#define SIMDJSON_GENERIC_COMPILE_TIME_JSON_H
+
+#if SIMDJSON_STATIC_REFLECTION
+
+#include <algorithm>
+#include <array>
+#include <charconv>
+#include <cstdint>
+#include <expected>
+#include <meta>
+#include <string>
+#include <string_view>
+#include <vector>
+
+namespace simdjson {
+namespace compile_time {
+
+/**
+ * @brief Compile-time JSON parser. This function parses the provided JSON
+ * string at compile time and returns a custom struct type representing the JSON
+ * object.
+ *
+ * We have a few limitations which trigger compile-time errors if violated:
+ * - Only JSON objects and arrays are supported at the top level (no primitives).
+ *   We will lift this limitation in the future.
+ * - Strings are represented using the const char * in UTF-8, but they must not
+ *   contain embedded nulls. We would prefer to represent them as std::string or
+ *   std::string_view, and hope to do so in the future.
+ * - Heterogeneous arrays are not supported yet. E.g., you need to have arrays of
+ *   all integers, or all strings, all floats, all compatible objects, etc.
+ *   For example, the following is accepted:
+ *    [
+ *     { "name": "Alice", "age": 30 },
+ *     { "name": "Bob", "age": 25 },
+ *     { "name": "Charlie", "age": 35 }
+ *   ]
+ *   but the following is not:
+ *   [
+ *     { "name": "Alice", "age": 30 },
+ *     "Just a string",
+ *     42,
+ *     { "name": "Charlie", "age": 35 }
+ *   ]
+ *
+ *    We may support heterogeneous arrays in the future with std::variant types.
+ * - We parse the first JSON document encountered in the string. Trailing
+ *   characters are ignored. Thus if your JSON begins with {"a":1}, everything
+ *   after the closing } is ignored. This limitation will be lifted in the future,
+ *   reporting an error.
+ *
+ * These limitations are safe in the sense that they result in compile-time errors.
+ * Thus you will not get truncated strings or imprecise floats silently.
+ *
+ * This function is subject to change in the future.
+ */
+template <constevalutil::fixed_string json_str> consteval auto parse_json();
+
+} // namespace compile_time
+} // namespace simdjson
+
+
+template <simdjson::constevalutil::fixed_string str>
+consteval auto operator ""_json() {
+  return simdjson::compile_time::parse_json<str>();
+}
+
+#endif // SIMDJSON_STATIC_REFLECTION
+#endif // SIMDJSON_GENERIC_COMPILE_TIME_JSON_H

include/simdjson/compiler_check.h

@@ -13,6 +13,11 @@
 #endif
 #endif
 
+// C++ 26
+#if !defined(SIMDJSON_CPLUSPLUS26) && (SIMDJSON_CPLUSPLUS >= 202402L) // update when the standard is finalized
+#define SIMDJSON_CPLUSPLUS26 1
+#endif
+
 // C++ 23
 #if !defined(SIMDJSON_CPLUSPLUS23) && (SIMDJSON_CPLUSPLUS >= 202302L)
 #define SIMDJSON_CPLUSPLUS23 1
@@ -81,24 +86,38 @@
 #endif
 #endif
 
+#if defined(__cpp_lib_ranges) && __cpp_lib_ranges >= 201911L
+#include <ranges>
+#define SIMDJSON_SUPPORTS_RANGES 1
+#else
+#define SIMDJSON_SUPPORTS_RANGES 0
+#endif
 
 #if defined(__cpp_concepts) && !defined(SIMDJSON_CONCEPT_DISABLED)
 #if __cpp_concepts >= 201907L
 #include <utility>
+#define SIMDJSON_SUPPORTS_CONCEPTS 1
+#else
+#define SIMDJSON_SUPPORTS_CONCEPTS 0
+#endif
+#else // defined(__cpp_concepts) && !defined(SIMDJSON_CONCEPT_DISABLED)
+#define SIMDJSON_SUPPORTS_CONCEPTS 0
+#endif // defined(__cpp_concepts) && !defined(SIMDJSON_CONCEPT_DISABLED)
+
+// copy SIMDJSON_SUPPORTS_CONCEPTS to SIMDJSON_SUPPORTS_DESERIALIZATION.
+#if SIMDJSON_SUPPORTS_CONCEPTS
 #define SIMDJSON_SUPPORTS_DESERIALIZATION 1
 #else
 #define SIMDJSON_SUPPORTS_DESERIALIZATION 0
 #endif
-#else // defined(__cpp_concepts) && !defined(SIMDJSON_CONCEPT_DISABLED)
+
-#define SIMDJSON_SUPPORTS_DESERIALIZATION 0
-#endif // defined(__cpp_concepts) && !defined(SIMDJSON_CONCEPT_DISABLED)
 
 #if !defined(SIMDJSON_CONSTEVAL)
-#if defined(__cpp_consteval) && __cpp_consteval >= 201811L
+#if defined(__cpp_consteval) && __cpp_consteval >= 201811L && defined(__cpp_lib_constexpr_string) && __cpp_lib_constexpr_string >= 201907L
 #define SIMDJSON_CONSTEVAL 1
 #else
 #define SIMDJSON_CONSTEVAL 0
-#endif // defined(__cpp_consteval) && __cpp_consteval >= 201811L
+#endif // defined(__cpp_consteval) && __cpp_consteval >= 201811L && defined(__cpp_lib_constexpr_string) && __cpp_lib_constexpr_string >= 201907L
 #endif // !defined(SIMDJSON_CONSTEVAL)
 
 #endif // SIMDJSON_COMPILER_CHECK_H

include/simdjson/concepts.h

@@ -1,6 +1,6 @@
 #ifndef SIMDJSON_CONCEPTS_H
 #define SIMDJSON_CONCEPTS_H
-#if SIMDJSON_SUPPORTS_DESERIALIZATION
+#if SIMDJSON_SUPPORTS_CONCEPTS
 
 #include <concepts>
 #include <type_traits>
@@ -32,7 +32,9 @@ SIMDJSON_IMPL_CONCEPT(op_append, operator+=)
 #undef SIMDJSON_IMPL_CONCEPT
 } // namespace details
 
-
+template <typename T>
+concept is_pair = requires { typename T::first_type; typename T::second_type; } &&
+                  std::same_as<T, std::pair<typename T::first_type, typename T::second_type>>;
 template <typename T>
 concept string_view_like = std::is_convertible_v<T, std::string_view> &&
                            !std::is_convertible_v<T, const char*>;
@@ -120,11 +122,65 @@ concept optional_type = requires(std::remove_cvref_t<T> obj) {
     } -> std::convertible_to<typename std::remove_cvref_t<T>::value_type>;
   };
   { static_cast<bool>(obj) } -> std::same_as<bool>; // convertible to bool
+  { obj.reset() } noexcept -> std::same_as<void>;
 };
 
 
 
+// Types we serialize as JSON strings (not as containers)
+template <typename T>
+concept string_like =
+  std::is_same_v<std::remove_cvref_t<T>, std::string> ||
+  std::is_same_v<std::remove_cvref_t<T>, std::string_view> ||
+  std::is_same_v<std::remove_cvref_t<T>, const char*> ||
+  std::is_same_v<std::remove_cvref_t<T>, char*>;
+
+// Concept that checks if a type is a container but not a string (because
+// strings handling must be handled differently)
+// Now uses iterator-based approach for broader container support
+template <typename T>
+concept container_but_not_string =
+  std::ranges::input_range<T> && !string_like<T> && !concepts::string_view_keyed_map<T>;
+
+
+
+// Concept: Indexable container that is not a string or associative container
+// Accepts: std::vector, std::array, std::deque (have operator[], value_type, not string_like)
+// Rejects: std::string (string_like), std::list (no operator[]), std::map (has key_type)
+template<typename Container>
+concept indexable_container = requires {
+  typename Container::value_type;
+  requires !concepts::string_like<Container>;
+  requires !requires { typename Container::key_type; };  // Reject maps/sets
+  requires requires(Container& c, std::size_t i) {
+    { c[i] } -> std::convertible_to<typename Container::value_type>;
+  };
+};
+
+
+// Variable template to use with std::meta::substitute
+template<typename Container>
+constexpr bool indexable_container_v = indexable_container<Container>;
+
 } // namespace concepts
+
+
+/**
+ * We use tag_invoke as our customization point mechanism.
+ */
+template <typename Tag, typename... Args>
+concept tag_invocable = requires(Tag tag, Args... args) {
+  tag_invoke(std::forward<Tag>(tag), std::forward<Args>(args)...);
+};
+
+template <typename Tag, typename... Args>
+concept nothrow_tag_invocable =
+    tag_invocable<Tag, Args...> && requires(Tag tag, Args... args) {
+      {
+        tag_invoke(std::forward<Tag>(tag), std::forward<Args>(args)...)
+      } noexcept;
+    };
+
 } // namespace simdjson
-#endif // SIMDJSON_SUPPORTS_DESERIALIZATION
+#endif // SIMDJSON_SUPPORTS_CONCEPTS
 #endif // SIMDJSON_CONCEPTS_H

include/simdjson/constevalutil.h

@@ -0,0 +1,89 @@
+#ifndef SIMDJSON_CONSTEVALUTIL_H
+#define SIMDJSON_CONSTEVALUTIL_H
+
+#include <string>
+#include <string_view>
+#include <array>
+
+namespace simdjson {
+namespace constevalutil {
+#if SIMDJSON_CONSTEVAL
+
+constexpr static std::array<uint8_t, 256> json_quotable_character = {
+  1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,
+  1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+  0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+  0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0,
+  0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+  0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+  0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+  0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+  0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+  0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+  0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0};
+constexpr static std::array<std::string_view, 32> control_chars = {
+    "\\u0000", "\\u0001", "\\u0002", "\\u0003", "\\u0004", "\\u0005", "\\u0006",
+    "\\u0007", "\\b", "\\t",     "\\n",     "\\u000b", "\\f",     "\\r",
+    "\\u000e", "\\u000f", "\\u0010", "\\u0011", "\\u0012", "\\u0013", "\\u0014",
+    "\\u0015", "\\u0016", "\\u0017", "\\u0018", "\\u0019", "\\u001a", "\\u001b",
+    "\\u001c", "\\u001d", "\\u001e", "\\u001f"};
+// unoptimized, meant for compile-time execution
+consteval std::string consteval_to_quoted_escaped(std::string_view input) {
+  std::string out = "\"";
+  for (char c : input) {
+    if (json_quotable_character[uint8_t(c)]) {
+      if (c == '"') {
+        out.append("\\\"");
+      } else if (c == '\\') {
+        out.append("\\\\");
+      } else {
+        std::string_view v = control_chars[uint8_t(c)];
+        out.append(v);
+      }
+    } else {
+      out.push_back(c);
+    }
+  }
+  out.push_back('"');
+  return out;
+}
+#endif  // SIMDJSON_CONSTEVAL
+
+
+#if SIMDJSON_SUPPORTS_CONCEPTS
+template <size_t N>
+struct fixed_string {
+    constexpr fixed_string(const char (&str)[N])  {
+        for (std::size_t i = 0; i < N; ++i) {
+            data[i] = str[i];
+        }
+    }
+    char data[N];
+    constexpr std::string_view view() const { return {data, N - 1}; }
+    constexpr size_t size() const { return N ; }
+    constexpr operator std::string_view() const { return view(); }
+    constexpr char operator[](std::size_t index) const { return data[index]; }
+    constexpr bool operator==(const fixed_string& other) const {
+        if (N != other.size()) {
+            return false;
+        }
+        for (std::size_t i = 0; i < N; ++i) {
+            if (data[i] != other.data[i]) {
+                return false;
+            }
+        }
+        return true;
+    }
+};
+template <std::size_t N>
+fixed_string(const char (&)[N]) -> fixed_string<N>;
+
+template <fixed_string str>
+struct string_constant {
+    static constexpr std::string_view value = str.view();
+};
+#endif // SIMDJSON_SUPPORTS_CONCEPTS
+
+} // namespace constevalutil
+} // namespace simdjson
+#endif // SIMDJSON_CONSTEVALUTIL_H

include/simdjson/convert-inl.h

@@ -0,0 +1,135 @@
+
+#ifndef SIMDJSON_CONVERT_INL_H
+#define SIMDJSON_CONVERT_INL_H
+
+#include "simdjson/convert.h"
+#if SIMDJSON_SUPPORTS_CONCEPTS
+namespace simdjson {
+namespace convert {
+namespace internal {
+// auto_parser method definitions
+template <typename parser_type>
+inline auto_parser<parser_type>::auto_parser(parser_type &&parser, ondemand::document &&doc) noexcept requires(!std::is_pointer_v<parser_type>)
+  : m_parser{std::move(parser)}, m_doc{std::move(doc)} {}
+
+template <typename parser_type>
+inline auto_parser<parser_type>::auto_parser(parser_type &&parser, padded_string_view const str) noexcept requires(!std::is_pointer_v<parser_type>)
+  : m_parser{std::move(parser)}, m_doc{}, m_error{SUCCESS} {
+  m_error = m_parser.iterate(str).get(m_doc);
+}
+
+template <typename parser_type>
+inline auto_parser<parser_type>::auto_parser(std::remove_pointer_t<parser_type> &parser, ondemand::document &&doc) noexcept requires(std::is_pointer_v<parser_type>)
+  : m_parser{&parser}, m_doc{std::move(doc)} {}
+
+template <typename parser_type>
+inline auto_parser<parser_type>::auto_parser(std::remove_pointer_t<parser_type> &parser, padded_string_view const str) noexcept requires(std::is_pointer_v<parser_type>)
+  : m_parser{&parser}, m_doc{}, m_error{SUCCESS} {
+  m_error = m_parser->iterate(str).get(m_doc);
+}
+
+template <typename parser_type>
+inline auto_parser<parser_type>::auto_parser(padded_string_view const str) noexcept requires(std::is_pointer_v<parser_type>)
+  : auto_parser{ondemand::parser::get_parser(), str} {}
+
+template <typename parser_type>
+inline auto_parser<parser_type>::auto_parser(parser_type parser, ondemand::document &&doc) noexcept requires(std::is_pointer_v<parser_type>)
+  : auto_parser{*parser, std::move(doc)} {}
+
+
+
+
+
+template <typename parser_type>
+inline std::remove_pointer_t<parser_type> &auto_parser<parser_type>::parser() noexcept {
+  if constexpr (std::is_pointer_v<parser_type>) {
+    return *m_parser;
+  } else {
+    return m_parser;
+  }
+}
+
+template <typename parser_type>
+template <typename T>
+inline simdjson_result<T> auto_parser<parser_type>::result() noexcept(is_nothrow_gettable<T>) {
+  if (m_error != SUCCESS) {
+    return m_error;
+  }
+  return m_doc.get<T>();
+}
+
+template <typename parser_type>
+template <typename T>
+simdjson_warn_unused simdjson_inline error_code auto_parser<parser_type>::get(T &value) && noexcept(is_nothrow_gettable<T>) {
+  return result<T>().get(value);
+}
+
+template <typename parser_type>
+inline simdjson_result<ondemand::array> auto_parser<parser_type>::array() noexcept {
+  return result<ondemand::array>();
+}
+
+template <typename parser_type>
+inline simdjson_result<ondemand::object> auto_parser<parser_type>::object() noexcept {
+  return result<ondemand::object>();
+}
+
+template <typename parser_type>
+inline simdjson_result<ondemand::number> auto_parser<parser_type>::number() noexcept {
+  return result<ondemand::number>();
+}
+
+#if SIMDJSON_EXCEPTIONS
+template <typename parser_type>
+template <typename T>
+inline auto_parser<parser_type>::operator T() noexcept(false) {
+  if (m_error != SUCCESS) {
+    throw simdjson_error(m_error);
+  }
+  return m_doc.get<T>();
+}
+#endif // SIMDJSON_EXCEPTIONS
+
+template <typename parser_type>
+template <typename T>
+inline std::optional<T> auto_parser<parser_type>::optional() noexcept(is_nothrow_gettable<T>) {
+  if (m_error != SUCCESS) {
+    return std::nullopt;
+  }
+  T value;
+  if (m_doc.get<T>().get(value)) [[unlikely]] {
+    return std::nullopt;
+  }
+  return {std::move(value)};
+}
+
+// to_adaptor method definitions
+template <typename T>
+inline T to_adaptor<T>::operator()(simdjson_result<ondemand::value> &val) const noexcept {
+  return val.get<T>();
+}
+
+template <typename T>
+inline auto to_adaptor<T>::operator()(padded_string_view const str) const noexcept {
+  return auto_parser<ondemand::parser *>{str};
+}
+
+template <typename T>
+inline auto to_adaptor<T>::operator()(ondemand::parser &parser, padded_string_view const str) const noexcept {
+  return auto_parser<ondemand::parser *>{parser, str};
+}
+
+template <typename T>
+inline auto to_adaptor<T>::operator()(std::string str) const noexcept {
+  return auto_parser<ondemand::parser *>{pad_with_reserve(str)};
+}
+
+template <typename T>
+inline auto to_adaptor<T>::operator()(ondemand::parser &parser, std::string str) const noexcept {
+  return auto_parser<ondemand::parser *>{parser, pad_with_reserve(str)};
+}
+} // namespace internal
+} // namespace convert
+} // namespace simdjson
+#endif // SIMDJSON_SUPPORTS_CONCEPTS
+#endif // SIMDJSON_CONVERT_INL_H

include/simdjson/convert.h

@@ -0,0 +1,121 @@
+
+#ifndef SIMDJSON_CONVERT_H
+#define SIMDJSON_CONVERT_H
+
+#include "simdjson/ondemand.h"
+#include <optional>
+
+#if SIMDJSON_SUPPORTS_CONCEPTS
+
+
+namespace simdjson {
+namespace convert {
+namespace internal {
+
+/**
+ * A utility class for automatically parsing JSON documents.
+ * This template is NOT part of our public API.
+ * It is subject to changes.
+ * @private
+ */
+template <typename parser_type = ondemand::parser*>
+struct auto_parser {
+private:
+	parser_type m_parser;
+	ondemand::document m_doc;
+	error_code m_error{SUCCESS};
+
+	template <typename T>
+	static constexpr bool is_nothrow_gettable = requires(ondemand::document doc) {
+		{ doc.get<T>() } noexcept;
+	};
+public:
+	explicit auto_parser(parser_type &&parser, ondemand::document &&doc) noexcept requires(!std::is_pointer_v<parser_type>);
+	explicit auto_parser(parser_type &&parser, padded_string_view const str) noexcept requires(!std::is_pointer_v<parser_type>);
+	explicit auto_parser(std::remove_pointer_t<parser_type> &parser, ondemand::document &&doc) noexcept requires(std::is_pointer_v<parser_type>);
+	explicit auto_parser(std::remove_pointer_t<parser_type> &parser, padded_string_view const str) noexcept requires(std::is_pointer_v<parser_type>);
+	explicit auto_parser(padded_string_view const str) noexcept requires(std::is_pointer_v<parser_type>);
+	explicit auto_parser(parser_type parser, ondemand::document &&doc) noexcept requires(std::is_pointer_v<parser_type>);
+		auto_parser(auto_parser const &) = delete;
+		auto_parser &operator=(auto_parser const &) = delete;
+		auto_parser(auto_parser &&) noexcept = default;
+		auto_parser &operator=(auto_parser &&) noexcept = default;
+		~auto_parser() = default;
+
+	simdjson_warn_unused std::remove_pointer_t<parser_type> &parser() noexcept;
+
+	template <typename T>
+	simdjson_warn_unused simdjson_inline simdjson_result<T> result() noexcept(is_nothrow_gettable<T>);
+	template <typename T>
+	simdjson_warn_unused simdjson_inline error_code get(T &value) && noexcept(is_nothrow_gettable<T>);
+
+
+	simdjson_warn_unused simdjson_inline simdjson_result<ondemand::array> array() noexcept;
+	simdjson_warn_unused simdjson_inline simdjson_result<ondemand::object> object() noexcept;
+	simdjson_warn_unused simdjson_inline simdjson_result<ondemand::number> number() noexcept;
+
+
+#if SIMDJSON_EXCEPTIONS
+	template <typename T>
+	simdjson_warn_unused simdjson_inline explicit(false) operator T() noexcept(false);
+#endif // SIMDJSON_EXCEPTIONS
+
+	template <typename T>
+	simdjson_warn_unused simdjson_inline std::optional<T> optional() noexcept(is_nothrow_gettable<T>);
+};
+
+
+/**
+ * A utility class for adapting values for the `auto_parser`.
+ * This template is not part of our public API. It is subject to changes.
+ * @private
+ */
+template <typename T = void>
+struct to_adaptor {
+	T operator()(simdjson_result<ondemand::value> &val) const noexcept;
+	auto operator()(padded_string_view const str) const noexcept;
+	auto operator()(ondemand::parser &parser, padded_string_view const str) const noexcept;
+	// The std::string is padded with reserve to ensure there is enough space for padding.
+	// Some sanitizers may not like this, so you can use simdjson::pad instead.
+	// simdjson::from(simdjson::pad(str))
+	auto operator()(std::string str) const noexcept;
+	auto operator()(ondemand::parser &parser, std::string str) const noexcept;
+};
+// deduction guide
+auto_parser(padded_string_view const str) -> auto_parser<ondemand::parser*>;
+} // namespace internal
+} // namespace convert
+
+/**
+ * The simdjson::from instance is EXPERIMENTAL AND SUBJECT TO CHANGES.
+ *
+ * The `from` instance is a utility adaptor for parsing JSON strings into objects.
+ * It provides a convenient way to convert JSON data into C++ objects using the `auto_parser`.
+ *
+ * Example usage:
+ *
+ * ```cpp
+ * std::map<std::string, std::string> obj =
+ *   simdjson::from(R"({"key": "value"})"_padded);
+ * ```
+ *
+ * This will parse the JSON string and return an object representation. By default, we
+ * use the simdjson::ondemand::parser::get_parser() instance. A parser instance should
+ * be used for just one document at a time.
+ *
+ * You can also pass you own parser instance:
+ * ```cpp
+ * simdjson::ondemand::parser parser;
+ * std::map<std::string, std::string> obj =
+ *   simdjson::from(parser, R"({"key": "value"})"_padded);
+ * ```
+ * The parser instance can be reused.
+ *
+ * This functionality requires C++20 or better.
+ */
+static constexpr convert::internal::to_adaptor<> from{};
+
+} // namespace simdjson
+
+#endif // SIMDJSON_SUPPORTS_CONCEPTS
+#endif // SIMDJSON_CONVERT_H

include/simdjson/dom.h

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

include/simdjson/dom/array-inl.h

@@ -52,11 +52,22 @@ inline simdjson_result<dom::element> simdjson_result<dom::array>::at_pointer(std
   return at_pointer(json_pointer);
  }
 
+inline simdjson_result<std::vector<dom::element>> simdjson_result<dom::array>::at_path_with_wildcard(std::string_view json_path) const noexcept {
+  if (error()) {
+    return error();
+  }
+  return first.at_path_with_wildcard(json_path);
+}
+
 inline simdjson_result<dom::element> simdjson_result<dom::array>::at(size_t index) const noexcept {
   if (error()) { return error(); }
   return first.at(index);
 }
 
+inline std::vector<dom::element>& simdjson_result<dom::array>::get_values(std::vector<dom::element>& out) const noexcept {
+  return first.get_values(out);
+}
+
 namespace dom {
 
 //
@@ -127,6 +138,93 @@ inline simdjson_result<element> array::at_path(std::string_view json_path) const
   return at_pointer(json_pointer);
 }
 
+inline void array::process_json_path_of_child_elements(std::vector<element>::iterator& current, std::vector<element>::iterator& end, const std::string_view& path_suffix, std::vector<element>& accumulator) const noexcept {
+  if (current == end) {
+    return;
+  }
+
+  simdjson_result<std::vector<element>> result;
+
+
+  for (auto it = current; it != end; ++it) {
+    std::vector<element> child_result;
+    auto error = it->at_path_with_wildcard(path_suffix).get(child_result);
+    if(error) {
+      continue;
+    }
+    accumulator.reserve(accumulator.size() + child_result.size());
+    accumulator.insert(accumulator.end(),
+                        std::make_move_iterator(child_result.begin()),
+                        std::make_move_iterator(child_result.end()));
+  }
+}
+
+inline simdjson_result<std::vector<element>> array::at_path_with_wildcard(std::string_view json_path) const noexcept {
+  SIMDJSON_DEVELOPMENT_ASSERT(tape.usable()); // https://github.com/simdjson/simdjson/issues/1914
+
+  size_t i = 0;
+   // json_path.starts_with('$') requires C++20.
+  if (!json_path.empty() && json_path.front() == '$') {
+    i = 1;
+  }
+
+  if (i >= json_path.size() || (json_path[i] != '.' && json_path[i] != '[')) {
+    return INVALID_JSON_POINTER;
+  }
+
+  if (json_path.find("*") != std::string::npos) {
+    std::vector<element> child_values;
+
+    if (
+      (json_path.compare(i, 3, "[*]") == 0 && json_path.size() == i + 3) ||
+      (json_path.compare(i, 2,".*") == 0 && json_path.size() == i + 2)
+    ) {
+      get_values(child_values);
+      return child_values;
+    }
+
+    std::pair<std::string_view, std::string_view> key_and_json_path = get_next_key_and_json_path(json_path);
+
+    std::string_view key = key_and_json_path.first;
+    json_path = key_and_json_path.second;
+
+    if (key.size() > 0) {
+      if (key == "*") {
+        get_values(child_values);
+      } else {
+        element pointer_result;
+        std::string json_pointer = std::string("/") + std::string(key);
+        auto error = at_pointer(json_pointer).get(pointer_result);
+
+        if (!error) {
+          child_values.emplace_back(pointer_result);
+        }
+      }
+
+      std::vector<element> result = {};
+
+      if (child_values.size() > 0) {
+        std::vector<element>::iterator child_values_begin = child_values.begin();
+        std::vector<element>::iterator child_values_end = child_values.end();
+
+        process_json_path_of_child_elements(child_values_begin, child_values_end, json_path, result);
+      }
+
+      return result;
+    } else {
+      return INVALID_JSON_POINTER;
+    }
+  } else {
+    element result;
+    auto error = at_path(json_path).get(result);
+    if (error) {
+      return error;
+    }
+
+    return std::vector<element>{std::move(result)};
+  }
+}
+
 inline simdjson_result<element> array::at(size_t index) const noexcept {
   SIMDJSON_DEVELOPMENT_ASSERT(tape.usable()); // https://github.com/simdjson/simdjson/issues/1914
   size_t i=0;
@@ -137,6 +235,15 @@ inline simdjson_result<element> array::at(size_t index) const noexcept {
   return INDEX_OUT_OF_BOUNDS;
 }
 
+inline std::vector<element>& array::get_values(std::vector<element>& out) const noexcept {
+  out.reserve(this->size());
+  for (auto element : *this) {
+    out.emplace_back(element);
+  }
+
+  return out;
+}
+
 inline array::operator element() const noexcept {
 	return element(tape);
 }
@@ -183,13 +290,13 @@ inline bool array::iterator::operator>(const array::iterator& other) const noexc
 
 #include "simdjson/dom/element-inl.h"
 
-#if defined(__cpp_lib_ranges)
+#if SIMDJSON_SUPPORTS_RANGES
 static_assert(std::ranges::view<simdjson::dom::array>);
 static_assert(std::ranges::sized_range<simdjson::dom::array>);
 #if SIMDJSON_EXCEPTIONS
 static_assert(std::ranges::view<simdjson::simdjson_result<simdjson::dom::array>>);
 static_assert(std::ranges::sized_range<simdjson::simdjson_result<simdjson::dom::array>>);
 #endif // SIMDJSON_EXCEPTIONS
-#endif // defined(__cpp_lib_ranges)
+#endif // SIMDJSON_SUPPORTS_RANGES
 
 #endif // SIMDJSON_ARRAY_INL_H

include/simdjson/dom/array.h

@@ -1,6 +1,8 @@
 #ifndef SIMDJSON_DOM_ARRAY_H
 #define SIMDJSON_DOM_ARRAY_H
 
+#include <vector>
+
 #include "simdjson/dom/base.h"
 #include "simdjson/internal/tape_ref.h"
 
@@ -108,12 +110,23 @@ public:
    */
   inline simdjson_result<element> at_pointer(std::string_view json_pointer) const noexcept;
 
+  /**
+   * Recursive function which processes the JSON path of each child element
+   */
+  inline void process_json_path_of_child_elements(std::vector<element>::iterator& current, std::vector<element>::iterator& end, const std::string_view& path_suffix, std::vector<element>& accumulator) const noexcept;
+
+
+  /**
+   * Adds support for JSONPath expression with wildcards '*'
+   */
+  inline simdjson_result<std::vector<element>> at_path_with_wildcard(std::string_view json_path) const noexcept;
+
   /**
    * Get the value associated with the given JSONPath expression. We only support
    * JSONPath queries that trivially convertible to JSON Pointer queries: key
    * names and array indices.
    *
-   * https://datatracker.ietf.org/doc/html/draft-normington-jsonpath-00
+   * https://www.rfc-editor.org/rfc/rfc9535 (RFC 9535)
    *
    * @return The value associated with the given JSONPath expression, or:
    *         - INVALID_JSON_POINTER if the JSONPath to JSON Pointer conversion fails
@@ -141,6 +154,15 @@ public:
    */
   inline simdjson_result<element> at(size_t index) const noexcept;
 
+  /**
+   * Gets the values of items in an array element
+   * This function has linear-time complexity: the values are checked one by one.
+   *
+   * @return The child elements of an array
+   */
+
+  inline std::vector<element>& get_values(std::vector<element>& out) const noexcept;
+
   /**
    * Implicitly convert object to element
    */
@@ -167,8 +189,11 @@ public:
   simdjson_inline simdjson_result(error_code error) noexcept; ///< @private
 
   inline simdjson_result<dom::element> at_pointer(std::string_view json_pointer) const noexcept;
+  inline void process_json_path_of_child_elements(std::vector<dom::element>::iterator& current, std::vector<dom::element>::iterator& end, const std::string_view& path_suffix, std::vector<dom::element>& accumulator) const noexcept;
+  inline simdjson_result<std::vector<dom::element>> at_path_with_wildcard(std::string_view json_path) const noexcept;
   inline simdjson_result<dom::element> at_path(std::string_view json_path) const noexcept;
   inline simdjson_result<dom::element> at(size_t index) const noexcept;
+  inline std::vector<dom::element>& get_values(std::vector<dom::element>& out) const noexcept;
 
 #if SIMDJSON_EXCEPTIONS
   inline dom::array::iterator begin() const noexcept(false);
@@ -181,9 +206,7 @@ public:
 
 } // namespace simdjson
 
-#if defined(__cpp_lib_ranges)
+#if SIMDJSON_SUPPORTS_RANGES
-#include <ranges>
-
 namespace std {
 namespace ranges {
 template<>
@@ -194,6 +217,6 @@ inline constexpr bool enable_view<simdjson::simdjson_result<simdjson::dom::array
 #endif // SIMDJSON_EXCEPTIONS
 } // namespace ranges
 } // namespace std
-#endif // defined(__cpp_lib_ranges)
+#endif // SIMDJSON_SUPPORTS_RANGES
 
 #endif // SIMDJSON_DOM_ARRAY_H

include/simdjson/dom/document_stream.h

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

include/simdjson/dom/element-inl.h

@@ -128,6 +128,12 @@ simdjson_inline simdjson_result<dom::element> simdjson_result<dom::element>::at_
   if (json_pointer == "-1") { return INVALID_JSON_POINTER; }
   return at_pointer(json_pointer);
 }
+
+simdjson_inline simdjson_result<std::vector<dom::element>> simdjson_result<dom::element>::at_path_with_wildcard(const std::string_view json_path) const noexcept {
+  if (error()) { return error(); }
+  return first.at_path_with_wildcard(json_path);
+}
+
 #ifndef SIMDJSON_DISABLE_DEPRECATED_API
 [[deprecated("For standard compliance, use at_pointer instead, and prefix your pointers with a slash '/', see RFC6901 ")]]
 simdjson_inline simdjson_result<dom::element> simdjson_result<dom::element>::at(const std::string_view json_pointer) const noexcept {
@@ -418,6 +424,20 @@ inline simdjson_result<element> element::at_pointer(std::string_view json_pointe
     }
   }
 }
+
+inline simdjson_result<std::vector<element>> element::at_path_with_wildcard(std::string_view json_path) const noexcept {
+  SIMDJSON_DEVELOPMENT_ASSERT(tape.usable()); // https://github.com/simdjson/simdjson/issues/1914
+
+  switch (tape.tape_ref_type()) {
+    case internal::tape_type::START_OBJECT:
+      return object(tape).at_path_with_wildcard(json_path);
+    case internal::tape_type::START_ARRAY:
+      return array(tape).at_path_with_wildcard(json_path);
+    default:
+      return std::vector<element>{};
+  }
+}
+
 inline simdjson_result<element> element::at_path(std::string_view json_path) const noexcept {
   auto json_pointer = json_path_to_pointer_conversion(json_path);
   if (json_pointer == "-1") { return INVALID_JSON_POINTER; }

include/simdjson/dom/element.h

@@ -1,6 +1,8 @@
 #ifndef SIMDJSON_DOM_ELEMENT_H
 #define SIMDJSON_DOM_ELEMENT_H
 
+#include <vector>
+
 #include "simdjson/dom/base.h"
 #include "simdjson/dom/array.h"
 
@@ -399,12 +401,14 @@ public:
    */
   inline simdjson_result<element> at_pointer(const std::string_view json_pointer) const noexcept;
 
+  inline simdjson_result<std::vector<element>> at_path_with_wildcard(const std::string_view json_path) const noexcept;
+
   /**
    * Get the value associated with the given JSONPath expression. We only support
    * JSONPath queries that trivially convertible to JSON Pointer queries: key
    * names and array indices.
    *
-   * https://datatracker.ietf.org/doc/html/draft-normington-jsonpath-00
+   * https://www.rfc-editor.org/rfc/rfc9535 (RFC 9535)
    *
    * @return The value associated with the given JSONPath expression, or:
    *         - INVALID_JSON_POINTER if the JSONPath to JSON Pointer conversion fails
@@ -544,6 +548,7 @@ public:
   simdjson_inline simdjson_result<dom::element> operator[](const char *key) const noexcept;
   simdjson_result<dom::element> operator[](int) const noexcept = delete;
   simdjson_inline simdjson_result<dom::element> at_pointer(const std::string_view json_pointer) const noexcept;
+  simdjson_inline simdjson_result<std::vector<dom::element>> at_path_with_wildcard(const std::string_view json_path) const noexcept;
   simdjson_inline simdjson_result<dom::element> at_path(const std::string_view json_path) const noexcept;
   [[deprecated("For standard compliance, use at_pointer instead, and prefix your pointers with a slash '/', see RFC6901 ")]]
   simdjson_inline simdjson_result<dom::element> at(const std::string_view json_pointer) const noexcept;

include/simdjson/dom/fractured_json.h

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

include/simdjson/dom/object-inl.h

@@ -40,10 +40,19 @@ inline simdjson_result<dom::element> simdjson_result<dom::object>::at_path(std::
   if (json_pointer == "-1") { return INVALID_JSON_POINTER; }
   return at_pointer(json_pointer);
 }
+inline simdjson_result<std::vector<dom::element>> simdjson_result<dom::object>::at_path_with_wildcard(std::string_view json_path) const noexcept {
+  if (error()) {
+    return error();
+  }
+  return first.at_path_with_wildcard(json_path);
+}
 inline simdjson_result<dom::element> simdjson_result<dom::object>::at_key(std::string_view key) const noexcept {
   if (error()) { return error(); }
   return first.at_key(key);
 }
+inline std::vector<dom::element>& simdjson_result<dom::object>::get_values(std::vector<dom::element>& out) const noexcept {
+  return first.get_values(out);
+}
 inline simdjson_result<dom::element> simdjson_result<dom::object>::at_key_case_insensitive(std::string_view key) const noexcept {
   if (error()) { return error(); }
   return first.at_key_case_insensitive(key);
@@ -143,6 +152,97 @@ inline simdjson_result<element> object::at_path(std::string_view json_path) cons
   return at_pointer(json_pointer);
 }
 
+inline void object::process_json_path_of_child_elements(std::vector<element>::iterator& current, std::vector<element>::iterator& end, const std::string_view& path_suffix, std::vector<element>& accumulator) const noexcept {
+  if (current == end) {
+    return;
+  }
+
+  simdjson_result<std::vector<element>> result;
+
+  for (auto it = current; it != end; ++it) {
+    std::vector<element> child_result;
+    auto error = it->at_path_with_wildcard(path_suffix).get(child_result);
+    if(error) {
+      continue;
+    }
+    accumulator.reserve(accumulator.size() + child_result.size());
+    accumulator.insert(accumulator.end(),
+                        std::make_move_iterator(child_result.begin()),
+                        std::make_move_iterator(child_result.end()));
+  }
+}
+
+inline simdjson_result<std::vector<element>> object::at_path_with_wildcard(std::string_view json_path) const noexcept {
+  SIMDJSON_DEVELOPMENT_ASSERT(tape.usable()); // https://github.com/simdjson/simdjson/issues/1914
+
+  size_t i = 0;
+  if (json_path.empty()) {
+    return INVALID_JSON_POINTER;
+  }
+  // if JSONPath starts with $, skip it
+  // json_path.starts_with('$') requires C++20.
+  if (json_path.front() == '$') {
+    i = 1;
+  }
+
+  if (i >= json_path.size() || (json_path[i] != '.' && json_path[i] != '[')) {
+    // expect JSONPath expressions to always start with $ but this isn't currently
+    // expected in jsonpathutil.h.
+    return INVALID_JSON_POINTER;
+  }
+
+  if (json_path.find("*") != std::string::npos) {
+
+    std::vector<element> child_values;
+
+    if (
+      (json_path.compare(i, 3, "[*]") == 0 && json_path.size() == i + 3) ||
+      (json_path.compare(i, 2,".*") == 0 && json_path.size() == i + 2)
+    ) {
+      get_values(child_values);
+      return child_values;
+    }
+
+    std::pair<std::string_view, std::string_view> key_and_json_path = get_next_key_and_json_path(json_path);
+
+    std::string_view key = key_and_json_path.first;
+    json_path = key_and_json_path.second;
+
+    if (key.size() > 0) {
+      if (key == "*") {
+        get_values(child_values);
+      } else {
+        element pointer_result;
+        auto error = at_pointer(std::string("/") + std::string(key)).get(pointer_result);
+
+        if (!error) {
+          child_values.emplace_back(pointer_result);
+        }
+      }
+
+      std::vector<element> result = {};
+      if (child_values.size() > 0) {
+
+        std::vector<element>::iterator child_values_begin = child_values.begin();
+        std::vector<element>::iterator child_values_end = child_values.end();
+
+        process_json_path_of_child_elements(child_values_begin, child_values_end, json_path, result);
+      }
+
+      return result;
+    } else {
+      return INVALID_JSON_POINTER;
+    }
+  } else {
+    element result;
+    auto error = this->at_path(json_path).get(result);
+    if (error) {
+      return error;
+    }
+    return std::vector<element>{std::move(result)};
+  }
+}
+
 inline simdjson_result<element> object::at_key(std::string_view key) const noexcept {
   iterator end_field = end();
   for (iterator field = begin(); field != end_field; ++field) {
@@ -152,6 +252,18 @@ inline simdjson_result<element> object::at_key(std::string_view key) const noexc
   }
   return NO_SUCH_FIELD;
 }
+
+inline std::vector<element>& object::get_values(std::vector<element>& out) const noexcept {
+  iterator end_field = end();
+  iterator begin_field = begin();
+
+  out.reserve(std::distance(begin_field, end_field));
+  for (iterator field = begin_field; field != end_field; ++field) {
+    out.emplace_back(field.value());
+  }
+
+  return out;
+}
 // In case you wonder why we need this, please see
 // https://github.com/simdjson/simdjson/issues/323
 // People do seek keys in a case-insensitive manner.
@@ -263,13 +375,13 @@ inline key_value_pair::key_value_pair(std::string_view _key, element _value) noe
 
 } // namespace simdjson
 
-#if defined(__cpp_lib_ranges)
+#if SIMDJSON_SUPPORTS_RANGES
 static_assert(std::ranges::view<simdjson::dom::object>);
 static_assert(std::ranges::sized_range<simdjson::dom::object>);
 #if SIMDJSON_EXCEPTIONS
 static_assert(std::ranges::view<simdjson::simdjson_result<simdjson::dom::object>>);
 static_assert(std::ranges::sized_range<simdjson::simdjson_result<simdjson::dom::object>>);
 #endif // SIMDJSON_EXCEPTIONS
-#endif // defined(__cpp_lib_ranges)
+#endif // SIMDJSON_SUPPORTS_RANGES
 
 #endif // SIMDJSON_OBJECT_INL_H

include/simdjson/dom/object.h

@@ -1,6 +1,8 @@
 #ifndef SIMDJSON_DOM_OBJECT_H
 #define SIMDJSON_DOM_OBJECT_H
 
+#include <vector>
+
 #include "simdjson/dom/base.h"
 #include "simdjson/dom/element.h"
 #include "simdjson/internal/tape_ref.h"
@@ -172,12 +174,22 @@ public:
    */
   inline simdjson_result<element> at_pointer(std::string_view json_pointer) const noexcept;
 
+  /**
+   * Recursive function which processes the JSON path of each child element
+   */
+  inline void process_json_path_of_child_elements(std::vector<element>::iterator& current, std::vector<element>::iterator& end, const std::string_view& path_suffix, std::vector<element>& accumulator) const noexcept;
+
+  /**
+   * Adds support for JSONPath expression with wildcards '*'
+   */
+  inline simdjson_result<std::vector<element>> at_path_with_wildcard(std::string_view json_path) const noexcept;
+
   /**
    * Get the value associated with the given JSONPath expression. We only support
    * JSONPath queries that trivially convertible to JSON Pointer queries: key
    * names and array indices.
    *
-   * https://datatracker.ietf.org/doc/html/draft-normington-jsonpath-00
+   * https://www.rfc-editor.org/rfc/rfc9535 (RFC 9535)
    *
    * @return The value associated with the given JSONPath expression, or:
    *         - INVALID_JSON_POINTER if the JSONPath to JSON Pointer conversion fails
@@ -203,6 +215,14 @@ public:
    */
   inline simdjson_result<element> at_key(std::string_view key) const noexcept;
 
+  /**
+   * Gets the values associated with keys of an object
+   * This function has linear-time complexity: the keys are checked one by one.
+   *
+   * @return the values associated with each key of an object
+   */
+  inline std::vector<element>& get_values(std::vector<element>& out) const noexcept;
+
   /**
    * Get the value associated with the given key in a case-insensitive manner.
    * It is only guaranteed to work over ASCII inputs.
@@ -261,8 +281,11 @@ public:
   inline simdjson_result<dom::element> operator[](const char *key) const noexcept;
   simdjson_result<dom::element> operator[](int) const noexcept = delete;
   inline simdjson_result<dom::element> at_pointer(std::string_view json_pointer) const noexcept;
+  inline void process_json_path_of_child_elements(std::vector<dom::element>::iterator& current, std::vector<dom::element>::iterator& end, const std::string_view& path_suffix, std::vector<dom::element>& accumulator) const noexcept;
+  inline simdjson_result<std::vector<dom::element>> at_path_with_wildcard(std::string_view json_path_new) const noexcept;
   inline simdjson_result<dom::element> at_path(std::string_view json_path) const noexcept;
   inline simdjson_result<dom::element> at_key(std::string_view key) const noexcept;
+  inline std::vector<dom::element>& get_values(std::vector<dom::element>& out) const noexcept;
   inline simdjson_result<dom::element> at_key_case_insensitive(std::string_view key) const noexcept;
 
 #if SIMDJSON_EXCEPTIONS
@@ -274,9 +297,7 @@ public:
 
 } // namespace simdjson
 
-#if defined(__cpp_lib_ranges)
+#if SIMDJSON_SUPPORTS_RANGES
-#include <ranges>
-
 namespace std {
 namespace ranges {
 template<>
@@ -287,6 +308,6 @@ inline constexpr bool enable_view<simdjson::simdjson_result<simdjson::dom::objec
 #endif // SIMDJSON_EXCEPTIONS
 } // namespace ranges
 } // namespace std
-#endif // defined(__cpp_lib_ranges)
+#endif // SIMDJSON_SUPPORTS_RANGES
 
 #endif // SIMDJSON_DOM_OBJECT_H

include/simdjson/dom/parser-inl.h

@@ -35,11 +35,11 @@ inline bool parser::dump_raw_tape(std::ostream &os) const noexcept {
   return valid ? doc.dump_raw_tape(os) : false;
 }
 
-inline simdjson_result<size_t> parser::read_file(const std::string &path) noexcept {
+inline simdjson_result<size_t> parser::read_file(std::string_view path) noexcept {
   // Open the file
   SIMDJSON_PUSH_DISABLE_WARNINGS
   SIMDJSON_DISABLE_DEPRECATED_WARNING // Disable CRT_SECURE warning on MSVC: manually verified this is safe
-  std::FILE *fp = std::fopen(path.c_str(), "rb");
+  std::FILE *fp = std::fopen(path.data(), "rb");
   SIMDJSON_POP_DISABLE_WARNINGS
 
   if (fp == nullptr) {
@@ -91,18 +91,18 @@ inline simdjson_result<size_t> parser::read_file(const std::string &path) noexce
   return bytes_read;
 }
 
-inline simdjson_result<element> parser::load(const std::string &path) & noexcept {
+inline simdjson_result<element> parser::load(std::string_view path) & noexcept {
   return load_into_document(doc, path);
 }
 
-inline simdjson_result<element> parser::load_into_document(document& provided_doc, const std::string &path) & noexcept {
+inline simdjson_result<element> parser::load_into_document(document& provided_doc, std::string_view path) & noexcept {
   size_t len;
   auto _error = read_file(path).get(len);
   if (_error) { return _error; }
   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 {
+inline simdjson_result<document_stream> parser::load_many(std::string_view path, size_t batch_size) noexcept {
   size_t len;
   auto _error = read_file(path).get(len);
   if (_error) { return _error; }

include/simdjson/dom/parser.h

@@ -102,8 +102,8 @@ public:
    *         - 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(const std::string &path) & noexcept;
+  inline simdjson_result<element> load(std::string_view path) & noexcept;
-  inline simdjson_result<element> load(const std::string &path) &&  = delete ;
+  inline simdjson_result<element> load(std::string_view path) &&  = delete ;
 
   /**
    * Load a JSON document from a file into a provide document instance and return a temporary reference to it.
@@ -148,8 +148,8 @@ public:
    *         - 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, std::string_view path) & noexcept;
-  inline simdjson_result<element> load_into_document(document& doc, const std::string &path) && =delete;
+  inline simdjson_result<element> load_into_document(document& doc, std::string_view path) && =delete;
 
   /**
    * Parse a JSON document and return a temporary reference to it.
@@ -204,10 +204,7 @@ public:
    *
    * ### std::string references
    *
-   * If you pass a mutable std::string reference (std::string&), the parser will seek to extend
+   * Whenever you pass an std::string reference, the parser may access the bytes beyond the end of
-   * its capacity to SIMDJSON_PADDING bytes beyond the end of the string.
-   *
-   * Whenever you pass an std::string reference, the parser will access the bytes beyond the end of
    * the string but before the end of the allocated memory (std::string::capacity()).
    * If you are using a sanitizer that checks for reading uninitialized bytes or std::string's
    * container-overflow checks, you may encounter sanitizer warnings.
@@ -239,7 +236,7 @@ public:
   /** @overload parse(const uint8_t *buf, size_t len, bool realloc_if_needed) */
   simdjson_inline simdjson_result<element> parse(const char *buf, size_t len, bool realloc_if_needed = true) & noexcept;
   simdjson_inline simdjson_result<element> parse(const char *buf, size_t len, bool realloc_if_needed = true) && =delete;
-  /** @overload parse(const uint8_t *buf, size_t len, bool realloc_if_needed) */
+  /** @overload parse(const std::string &) */
   simdjson_inline simdjson_result<element> parse(const std::string &s) & noexcept;
   simdjson_inline simdjson_result<element> parse(const std::string &s) && =delete;
   /** @overload parse(const uint8_t *buf, size_t len, bool realloc_if_needed) */
@@ -386,7 +383,7 @@ public:
    *         - 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<document_stream> load_many(const std::string &path, size_t batch_size = dom::DEFAULT_BATCH_SIZE) noexcept;
+  inline simdjson_result<document_stream> load_many(std::string_view path, size_t batch_size = dom::DEFAULT_BATCH_SIZE) noexcept;
 
   /**
    * Parse a buffer containing many JSON documents.
@@ -657,7 +654,7 @@ private:
   inline error_code ensure_capacity(document& doc, size_t desired_capacity) noexcept;
 
   /** Read the file into loaded_bytes */
-  inline simdjson_result<size_t> read_file(const std::string &path) noexcept;
+  inline simdjson_result<size_t> read_file(std::string_view path) noexcept;
 
   friend class parser::Iterator;
   friend class document_stream;