Fixing typo

* tag_invoke based custom types (#2219)

* tag_invoke based custom types

Now you can use tag_invoke to add a custom type or a group of custom types.

* Fixing macro usage + Fixing noexcept

* Fixing the usage of #include

We don't need <concepts> at all seems like it

* Fixing tag_invoke impl for MSVC

* Making `tag_invoke` to support `ondemand::document` as well + docs (#2228)

* Making `tag_invoke` to support `ondemand::document` as well + docs

* Fix typos and doc update by @lemire

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

* Better docs by @lemire

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

* Preserving the old, disallowing in the new

I'm disabling `document::get() &&` if the user has provided a `tag_invoke`d version; otherwise, we retain the compatibility.

---------

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

* fix: correct small issues with deserialize (#2232)

* Extending the deserialization code with more defaults + docs (#2233)

* Make custom types easier with some predefined cases + docs

* missing include

* adding Ubuntu 24 CXX 20

* using concepts all the way

* minor tweak

* tiny tweak

* tweaks

* more tweaking

* saving

---------

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

* Making `tag_invoke` a "put" as opposed to a "get" (#2256)

* fix: add tests related to issue 2227 (#2229)

* fix: add tests related to issue 2227

* avoiding name clash

* pedantic fix

* deprecate rvalue get on document

* selectively deprecating

* Fix ndjson spec link (#2234)

* fix ndjson spec link

The link in the readme of parse_many links to a casino spam site

* fix link

* [no-ci] Update README.md

* Make simdjson compile again

* Enable SIMDJSON_SINGLEHEADER=OFF in VS Code

With singleheader on, clangd can't find the right
include files.

* Add missing include directives to static build targets of simdjson. (#2240)

* adding a warning

* adding warning regarding SIMDJSON_BUILD_STATIC_LIB

* release candidate

* pedantic viable size

* Making tag_invoke a feeder instead of a producer

* adding missing undef silencer (#2253)

* Ignore pragma once when amalgamating source files (#2248)

With gcc it causes an error in `simdjson.cpp`:
```
simdjson.cpp:548:9: warning: #pragma once in main file
  548 | #pragma once
      |         ^~~~
```

It had previously been commented out in:
https://github.com/simdjson/simdjson/commit/6ef555e6fb79363fae057a9a46b52cd208d9e305

However, this was lost in an upgrade:
https://github.com/simdjson/simdjson/commit/2a4ff7346813b120f2b5b40e95d69352b593cc9c

* Update CI (#2254)

* adding missing undef silencer

* Updating CI

* more fixes

* fix

* big endian fix

* Moving to the new tag_invoke signature

* Fix nlohmann ambiguity on C++23-enabled clang

* Revert "Merge branch 'master' of https://github.com/simdjson/simdjson into builder_development_branch_extra"

This reverts commit 3eeecbab34, reversing
changes made to 6858b208b4.

---------

Co-authored-by: Daniel Lemire <daniel@lemire.me>
Co-authored-by: Sasha Lopoukhine <superlopuh@gmail.com>
Co-authored-by: John Keiser <john@johnkeiser.com>
Co-authored-by: Tan Li Boon <undisputed-seraphim@users.noreply.github.com>
Co-authored-by: tobil4sk <tobil4sk@outlook.com>

* update CI on the builder_development_branch (no code change) (#2262)

* typo

* General madness simpler, no simpler!!! (#2267)

* Minimal tag_invokes for STL types

* simpler madness

* adding a comment

* missing file

* minor tweaks to style

* fixing incorrect max/min usage

* updating single

* simplify

* validating the idea

* putting back the concept

* moving the include

* guarding

* Cheap General Madness (#2268)

* Some General Concepts and their deserializations

* Resolving ambiguity

* Add missing #include

* C++20 custom deserializer: better documentation (#2269)

* mostly a documentation update.

* missing cpp

* [no-ci] fix comment

* various minor fixes

---------

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

---------

Co-authored-by: M. Bahoosh <12122474+the-moisrex@users.noreply.github.com>
Co-authored-by: Daniel Lemire <dlemire@lemire.me>
Co-authored-by: M. Bahoosh <moisrex@gmail.com>

* minor update

* More documentation regarding builder (#2270)

* minor update

* more improvment to our documentation (builder branch)

* putting back missing functions

* merge candidate

---------

Co-authored-by: M. Bahoosh <moisrex@gmail.com>
Co-authored-by: Daniel Lemire <dlemire@lemire.me>
Co-authored-by: Sasha Lopoukhine <superlopuh@gmail.com>
Co-authored-by: John Keiser <john@johnkeiser.com>
Co-authored-by: Tan Li Boon <undisputed-seraphim@users.noreply.github.com>
Co-authored-by: tobil4sk <tobil4sk@outlook.com>
Co-authored-by: M. Bahoosh <12122474+the-moisrex@users.noreply.github.com>

.github/workflows/ubuntu24-cxx20.yml

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

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

@@ -10,7 +10,6 @@ jobs:
        fail-fast: false
        matrix:
          include:
-           - {arch: ARM}
            - {arch: ARM64}
            - {arch: ARM64EC}
      steps:

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

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

.vscode/settings.json

@@ -109,11 +109,23 @@
         "numbers": "cpp",
         "semaphore": "cpp",
         "stop_token": "cpp",
-        "cfenv": "cpp"
+        "cfenv": "cpp",
-    },
+        "format": "cpp",
-    "cmake.configureSettings": {
+        "xlocmes": "cpp",
-        "CMAKE_EXPORT_COMPILE_COMMANDS": "YES",
+        "xlocmon": "cpp",
-        "SIMDJSON_DEVELOPER_MODE": "ON",
+        "xlocnum": "cpp",
-        "SIMDJSON_SINGLEHEADER": "OFF"
+        "xloctime": "cpp",
+        "xutility": "cpp",
+        "coroutine": "cpp",
+        "xfacet": "cpp",
+        "xhash": "cpp",
+        "xiosbase": "cpp",
+        "xlocale": "cpp",
+        "xlocbuf": "cpp",
+        "xlocinfo": "cpp",
+        "xmemory": "cpp",
+        "xstring": "cpp",
+        "xtr1common": "cpp",
+        "xtree": "cpp"
     }
 }

benchmark/find_tweet/nlohmann_json.h

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

benchmark/json2msgpack/simdjson_ondemand.h

@@ -50,7 +50,7 @@ private:
                                               uint8_t *p) noexcept;
   simdjson_inline void
   write_raw_string(simdjson::ondemand::raw_json_string rjs);
-  inline void recursive_processor(simdjson::ondemand::value&& element);
+  inline void recursive_processor(simdjson::ondemand::value element);
   inline void recursive_processor_ref(simdjson::ondemand::value& element);
 
   simdjson::ondemand::parser parser;
@@ -90,13 +90,12 @@ simdjson2msgpack::to_msgpack(const simdjson::padded_string &json,
   } else {
     simdjson::ondemand::value val = doc;
 #define SIMDJSON_GCC_COMPILER ((__GNUC__) && !(__clang__) && !(__INTEL_COMPILER))
-#if 1
+#if SIMDJSON_GCC_COMPILER
-//SIMDJSON_GCC_COMPILER
     // the GCC compiler does well with by-value passing.
     // GCC has superior recursive inlining:
     // https://stackoverflow.com/questions/29186186/why-does-gcc-generate-a-faster-program-than-clang-in-this-recursive-fibonacci-co
     // https://godbolt.org/z/TeK4doE51
-    recursive_processor(std::move(val));
+    recursive_processor(val);
 #else
     recursive_processor_ref(val);
 #endif
@@ -141,7 +140,7 @@ void simdjson2msgpack::write_raw_string(
   write_uint32_at(uint32_t(v.size()), location);
 }
 
-void simdjson2msgpack::recursive_processor(simdjson::ondemand::value&& element) {
+void simdjson2msgpack::recursive_processor(simdjson::ondemand::value element) {
   switch (element.type()) {
   case simdjson::ondemand::json_type::array: {
     uint32_t counter = 0;
@@ -149,7 +148,7 @@ void simdjson2msgpack::recursive_processor(simdjson::ondemand::value&& element)
     uint8_t *location = skip_uint32();
     for (auto child : element.get_array()) {
       counter++;
-      recursive_processor(std::move(child.value()));
+      recursive_processor(child.value());
     }
     write_uint32_at(counter, location);
   } break;

benchmark/top_tweet/nlohmann_json.h

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

doc/basics.md

@@ -17,6 +17,8 @@ An overview of what you need to know to use simdjson, with examples.
   - [Using the parsed JSON](#using-the-parsed-json)
     - [Using the parsed JSON: additional examples](#using-the-parsed-json-additional-examples)
   - [Adding support for custom types](#adding-support-for-custom-types)
+    - [1. Specialize `simdjson::ondemand::value::get` to get custom types (pre-C++20)](#1-specialize-simdjsonondemandvalueget-to-get-custom-types-pre-c20)
+    - [2. Use `tag_invoke` for custom types (C++20)](#2-use-tag_invoke-for-custom-types-c20)
   - [Minifying JSON strings without parsing](#minifying-json-strings-without-parsing)
   - [UTF-8 validation (alone)](#utf-8-validation-alone)
   - [JSON Pointer](#json-pointer)
@@ -526,7 +528,7 @@ support for users who avoid exceptions. See [the simdjson error handling documen
   double value;
   auto doc = parser.iterate(abstract_json);
   auto error = doc["str"]["123"]["abc"].get(value);
-  if (error) { std::cerr << error << std::endl; return EXIT_FAILURE; }
+  if (error) { std::cerr << simdjson::error_message(error) << std::endl; return EXIT_FAILURE; }
   cout << value << endl; // Prints 3.14
   ```
   This examples also show how we can string several operations and only check for the error once, a strategy we call  *error chaining*.
@@ -788,6 +790,18 @@ for (ondemand::object points : parser.iterate(points_json)) {
 Adding support for custom types
 ----------------------
 
+There are 2 main ways provided by simdjson to deserialize a value into a custom type:
+
+1. Provide a [**template specialization** for member functions](https://en.cppreference.com/w/cpp/language/template_specialization#Members_of_specializations)
+   1. Specialize `simdjson::ondemand::document::get` for the whole document
+   2. Specialize `simdjson::ondemand::value::get` for each value
+2. Using `tag_invoke` *(the recommended way if your system supports C++20 or better)*
+
+We describe both of them in the following sections. Most users who have systems compatible with
+C++20 or better should skip ahead to [using `tag_invoke` for custom types (C++20)](#2-use-tag_invoke-for-custom-types-c20) as it is more powerful and simpler.
+
+### 1. Specialize `simdjson::ondemand::value::get` to get custom types (pre-C++20)
+
 Suppose you have your own types, such as a `Car` struct:
 
 ```C++
@@ -821,9 +835,15 @@ type:
 ```
 
 We may do so by providing additional template definitions to the `ondemand::value` type.
-We may start by providing a definition for `std::vector<double>` as follows:
+We may start by providing a definition for `std::vector<double>` as follows. Observe
+how we guard the code with `#if !SIMDJSON_SUPPORTS_DESERIALIZATION`: that is because the necessary code
+is automatically provided by simdjson if C++20 (and concepts) are available.
+See [Use `tag_invoke` for custom types](#2-use-tag_invoke-for-custom-types-c20) if you have
+C++20 support.
 
 ```c++
+#if !SIMDJSON_SUPPORTS_DESERIALIZATION
+// The code is unnecessary with C++20:
 template <>
 simdjson_inline simdjson_result<std::vector<double>>
 simdjson::ondemand::value::get() noexcept {
@@ -839,6 +859,7 @@ simdjson::ondemand::value::get() noexcept {
   }
   return vec;
 }
+#endif
 ```
 
 We may then provide support for our `Car` struct:
@@ -850,26 +871,10 @@ simdjson_inline simdjson_result<Car> simdjson::ondemand::value::get() noexcept {
   auto error = get_object().get(obj);
   if (error) { return error; }
   Car car;
-  // Instead of repeatedly obj["something"], we iterate through the object which
+  if((error = obj["make"].get_string(car.make))) { return error; }
-  // we expect to be faster.
+  if((error = obj["model"].get_string(car.model))) { return error; }
-  for (auto field : obj) {
+  if((error = obj["year"].get_int64().get(car.year))) { return error; }
-    raw_json_string key;
+  if((error = obj["tire_pressure"].get<std::vector<double>>().get(car.tire_pressure))) { return error; }
-    error = field.key().get(key);
-    if (error) { return error; }
-    if (key == "make") {
-      error = field.value().get_string(car.make);
-      if (error) { return error; }
-    } else if (key == "model") {
-      error = field.value().get_string(car.model);
-      if (error) { return error; }
-    } else if (key == "year") {
-      error = field.value().get_int64().get(car.year);
-      if (error) { return error; }
-    } else if (key == "tire_pressure") {
-      error = field.value().get<std::vector<double>>().get(car.tire_pressure);
-      if (auto  error) { return error; }
-    }
-  }
   return car;
 }
 ```
@@ -893,6 +898,8 @@ struct Car {
   std::vector<double> tire_pressure;
 };
 
+#if !SIMDJSON_SUPPORTS_DESERIALIZATION
+// This code is not necessary if you have a C++20 compliant system:
 template <>
 simdjson_inline simdjson_result<std::vector<double>>
 simdjson::ondemand::value::get() noexcept {
@@ -908,7 +915,7 @@ simdjson::ondemand::value::get() noexcept {
   }
   return vec;
 }
-
+#endif
 
 template <>
 simdjson_inline simdjson_result<Car> simdjson::ondemand::value::get() noexcept {
@@ -916,26 +923,10 @@ simdjson_inline simdjson_result<Car> simdjson::ondemand::value::get() noexcept {
   auto error = get_object().get(obj);
   if (error) { return error; }
   Car car;
-  // Instead of repeatedly obj["something"], we iterate through the object which
+  if((error = obj["make"].get_string(car.make))) { return error; }
-  // we expect to be faster.
+  if((error = obj["model"].get_string(car.model))) { return error; }
-  for (auto field : obj) {
+  if((error = obj["year"].get_int64().get(car.year))) { return error; }
-    raw_json_string key;
+  if((error = obj["tire_pressure"].get<std::vector<double>>().get(car.tire_pressure))) { return error; }
-    error = field.key().get(key);
-    if (error) { return error; }
-    if (key == "make") {
-      error = field.value().get_string(car.make);
-      if (error) { return error; }
-    } else if (key == "model") {
-      error = field.value().get_string(car.model);
-      if (error) { return error; }
-    } else if (key == "year") {
-      error = field.value().get_int64().get(car.year);
-      if (error) { return error; }
-    } else if (key == "tire_pressure") {
-      error = field.value().get<std::vector<double>>().get(car.tire_pressure);
-      if (error) { return error; }
-    }
-  }
   return car;
 }
 
@@ -950,15 +941,14 @@ int main(void) {
   ondemand::parser parser;
   ondemand::document doc = parser.iterate(json);
   for (auto val : doc) {
-    Car c(val);
+    Car c(val); // an exception may be thrown
     std::cout << c.make << std::endl;
   }
-  direct();
   return EXIT_SUCCESS;
 }
 ```
 
-Observe that we require an explicit cast (`Car c(val)` instead of `for (Car c : doc) {`): it is by design.
+Observe that we require an explicit cast (`Car c(val)` instead of `for (Car c : doc) {`): it is by design. We require explicit casting.
 
 If you prefer to avoid exceptions, you may modify the `main` function as follows:
 
@@ -974,11 +964,11 @@ int main(void) {
   ondemand::parser parser;
   ondemand::document doc;
   auto error = parser.iterate(json).get(doc);
-  if (error) { std::cerr << error << std::endl; return EXIT_FAILURE; }
+  if (error) { std::cerr << simdjson::error_message(error) << std::endl; return EXIT_FAILURE; }
   for (auto val : doc) {
     Car c;
     error = val.get<Car>().get(c);
-    if (error) { std::cerr << error << std::endl; return EXIT_FAILURE; }
+    if (error) { std::cerr << simdjson::error_message(error) << std::endl; return EXIT_FAILURE; }
     std::cout << c.make << std::endl;
   }
   return EXIT_SUCCESS;
@@ -1009,49 +999,49 @@ struct Car {
   std::vector<double> tire_pressure;
 };
 
+#if !SIMDJSON_SUPPORTS_DESERIALIZATION
+// This code is not necessary if you have a C++20 compliant system:
 template <>
 simdjson_inline simdjson_result<std::vector<double>>
 simdjson::ondemand::value::get() noexcept {
   ondemand::array array;
-  if (auto error = get_array().get(array); error) { return error; }
+  auto error = get_array().get(array);
+  if (error) { return error; }
   std::vector<double> vec;
   for (auto v : array) {
     double val;
-    if (auto error = v.get_double().get(val); error) { return error; }
+    error = v.get_double().get(val);
+    if (error) { return error; }
     vec.push_back(val);
   }
   return vec;
 }
-
+#endif
 
 template <>
 simdjson_inline simdjson_result<Car> simdjson::ondemand::document::get() & noexcept {
   ondemand::object obj;
   auto error = get_object().get(obj);
-  if (error) {
+  if (error) { return error; }
-    return error;
-  }
   Car car;
-  // Instead of repeatedly obj["something"], we iterate through the object which
+  if((error = obj["make"].get_string(car.make))) { return error; }
-  // we expect to be faster.
+  if((error = obj["model"].get_string(car.model))) { return error; }
-  for (auto field : obj) {
+  if((error = obj["year"].get_int64().get(car.year))) { return error; }
-    raw_json_string key;
+  if((error = obj["tire_pressure"].get<std::vector<double>>().get(car.tire_pressure))) { return error; }
-    error = field.key().get(key);
+  return car;
-    if (error) { return error; }
-    if (key == "make") {
-      error = field.value().get_string(car.make);
-      if (error) { return error; }
-    } else if (key == "model") {
-      error = field.value().get_string(car.model);
-      if (error) { return error; }
-    } else if (key == "year") {
-      error = field.value().get_int64().get(car.year);
-      if (error) { return error; }
-    } else if (key == "tire_pressure") {
-      error = field.value().get<std::vector<double>>().get(car.tire_pressure);
-      if (error) { return error; }
-    }
 }
+
+
+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; }
+  if((error = obj["tire_pressure"].get<std::vector<double>>().get(car.tire_pressure))) { return error; }
   return car;
 }
 
@@ -1066,6 +1056,219 @@ int main(void) {
 }
 ```
 
+### 2. Use `tag_invoke` for custom types (C++20)
+
+In C++20, the standard introduced the notion of *customization point*.
+A customization point is a function or function object that can be customized for different types. It allows library authors to provide default behavior while giving users the ability to override this behavior for specific types.
+
+A tag_invoke function serves as a mechanism for customization points. It is not directly part of the C++ standard library but is often used in libraries that implement customization points.
+The tag_invoke function is typically a generic function that takes a tag type and additional arguments.
+The first argument is usually a tag type (often an empty struct) that uniquely identifies the customization point (e.g., deserialization of custom types in simdjson). Users or library providers can specialize tag_invoke for their types by defining it in the appropriate namespace, often inline namespace.
+
+
+If your system supports C++20, we recommend that you adopt the `tag_invoke` approach
+instead to deserialize custom types. It may prove to be considerably simpler. When
+simdjson detects the necessary support, it sets the `SIMDJSON_SUPPORTS_DESERIALIZATION` macro
+to 1, otherwise it is set to 0.
+
+Consider a custom class `Car`:
+
+```C++
+struct Car {
+  std::string make;
+  std::string model;
+  int year;
+  std::vector<float> tire_pressure;
+};
+```
+
+Observe how we defined the class to use types that simdjson does not directly support (`float`, `int`).
+With C++20 support, the library grabs from the JSON the generic type (`double`, `int`) and then it
+casts it automatically.
+
+You may support deserializing directly from a JSON value or document to your own `Car` instance
+by defining a single `tag_invoke` function:
+
+
+```C++
+namespace simdjson {
+// This tag_invoke MUST be inside simdjson namespace
+template <typename simdjson_value>
+auto tag_invoke(deserialize_tag, simdjson_value &val, Car& car) {
+  ondemand::object obj;
+  auto error = val.get_object().get(obj);
+  if (error) {
+    return error;
+  }
+  if ((error = obj["make"].get_string(car.make))) {
+    return error;
+  }
+  if ((error = obj["model"].get_string(car.model))) {
+    return error;
+  }
+  if ((error = obj["year"].get(car.year))) {
+    return error;
+  }
+  if ((error = obj["tire_pressure"].get<std::vector<float>>().get(
+           car.tire_pressure))) {
+    return error;
+  }
+  return simdjson::SUCCESS;
+}
+} // namespace simdjson
+```
+
+Observe how we call `get<std::vector<float>>()` even though we never defined support
+for `std::vector<float>` in the simdjson library: it is all automated thanks to C++20 concepts.
+
+Importantly, the `tag_invoke` function must be inside the `simdjson` namespace.
+Let us explain each argument of `tag_invoke` function.
+
+- `simdjson::deserialize_tag`: it is the tag for Customization Point Object (CPO). You may often ignore this parameter. It is used to indicate that you mean to provide a deserialization function for simdjson.
+- `var`: It receives automatically a `simdjson` value type (document, value, document_reference).
+- The third parameter is an instance of the type that you want to support.
+
+You can use it like so:
+
+```cpp
+  simdjson::padded_string json =
+      R"( { "make": "Toyota", "model": "Camry",  "year": 2018,
+       "tire_pressure": [ 40.1, 39.9 ] })"_padded;
+  simdjson::ondemand::parser parser;
+  simdjson::ondemand::document doc = parser.iterate(json);
+  Car c(doc);
+  std::cout << c.make << std::endl;
+```
+
+Observe how we first get an instance of `document` and then we cast.
+
+You can also handle errors explicitly:
+
+```cpp
+  Car c;
+  auto error = doc.get(c);
+  if(error) { std::cerr << simdjson::error_message(error); return false; }
+  std::cout << c.make << std::endl;
+```
+
+You can also read instances of `Car` from an array or an object:
+```cpp
+  simdjson::padded_string json =
+      R"( [ { "make": "Toyota", "model": "Camry",  "year": 2018,
+       "tire_pressure": [ 40.1, 39.9 ] },
+  { "make": "Kia",    "model": "Soul",   "year": 2012,
+       "tire_pressure": [ 30.1, 31.0 ] },
+  { "make": "Toyota", "model": "Tercel", "year": 1999,
+       "tire_pressure": [ 29.8, 30.0 ] }
+])"_padded;
+
+  simdjson::ondemand::parser parser;
+  simdjson::ondemand::document doc = parser.iterate(json);
+  for (auto val : doc) {
+    Car c(val); // an exception may be thrown
+    std::cout << c.year << std::endl;
+  }
+```
+
+Observe how we first get a generic (`val`) which we cast to `Car`. It is by design: we require
+explicit casting. The cast may throw an exception.
+
+Once more, you can handle errors explicitly:
+
+```cpp
+  for (auto val : doc) {
+    Car c;
+    auto error = val.get(c);
+    if(error) { std::cerr << simdjson::error_message(error) << std::endl; return false; }
+  }
+```
+
+You can also use the custom `Car` type as part of a template such as `std::vector`:
+
+```cpp
+  simdjson::ondemand::parser parser;
+  simdjson::ondemand::document doc = parser.iterate(json);
+  std::vector<Car> cars(doc);
+  // visual studio users need an explicit call:
+  //   std::vector<Car> cars = doc.get<std::vector<Car>>();
+  // because the compiler does not know whether to convert
+  // doc to an unsigned int or to a vector.
+  for(Car& c : cars) {
+    std::cout << c.year << std::endl;
+  }
+```
+
+By default, we support a wide range of standard templates such as
+`std::vector`,  `std::list`, `std::set`, `std::stack`, `std:queue`,
+`std:deque`, `std::priority_queue`, `std::unordered_set`, `std::multiset`,
+`std::unordered_multiset`, `std::unique_ptr`, `std::shared_ptr`, `std::optional`,
+etc. They are handled automatically.
+
+E.g., you can recover an `std::unique_ptr<Car>` like so:
+```C++
+int main() {
+  auto const json = R"( { "make": "Toyota", "model": "Camry",  "year": 2018,
+       "tire_pressure": [ 40.1, 39.9 ] })"_padded;
+  simdjson::ondemand::parser parser;
+  simdjson::ondemand::document doc = parser.iterate(json);
+  std::unique_ptr<Car> c(doc);
+  std::cout << c->make << std::endl;
+  return EXIT_SUCCESS;
+}
+```
+
+You may also conditionally fill in `std::optional` values.
+
+```C++
+
+  padded_string json =
+      R"( { "car1": { "make": "Toyota", "model": "Camry",  "year": 2018,
+       "tire_pressure": [ 40.1, 39.9 ] }
+})"_padded;
+  ondemand::parser parser;
+  ondemand::document doc = parser.iterate(json);
+  std::optional<Car> car;
+  error = doc["key not found"].get<std::optional<Car>>().get(car);
+  // car has no value, error != simdjson::SUCCESS
+  error = doc["car1"].get<std::optional<Car>>().get(car);
+  // car has value Car{"Toyota", "Camry", 2018, {40.1f, 39.9f}}
+  // error is simdjson::SUCCESS
+```
+
+And so forth.
+
+Advanced users may want to overwrite the defaults provided by the simdjson library.
+Suppose for example that you want to construct an instance of `std::list<Car>`, but
+you also want to filter out any car made by Toyota. You may provide your own
+`tag_invoke` function:
+
+```c++
+namespace simdjson {
+// suppose we want to filter out all Toyotas
+template <typename simdjson_value>
+auto tag_invoke(deserialize_tag, simdjson_value &val, std::list<Car>& car) {
+  ondemand::array arr;
+  auto error = val.get_array().get(arr);
+  if (error) {
+    return error;
+  }
+  for (auto v : arr) {
+    Car c;
+    if ((error = v.get<Car>().get(c))) {
+      return error;
+    }
+    if(c.make != "Toyota") {
+      car.push_back(c);
+    }
+  }
+  return simdjson::SUCCESS;
+}
+}
+```
+
+With this code, deserializing an `std::list<Car>` instance would capture only the cars
+that are not made by Toyota.
+
 
 Minifying JSON strings without parsing
 ----------------------
@@ -1081,6 +1284,7 @@ In some cases, you may have valid JSON strings that you do not wish to parse but
   std::unique_ptr<char[]> buffer{new char[length]};
   size_t new_length{}; // It will receive the minified length.
   auto error = simdjson::minify(some_string, length, buffer.get(), new_length);
+  if(error) { std::cerr << simdjson::error_message(error); }
   // The buffer variable now has "[1,2,3,4]" and new_length has value 9.
 ```
 
@@ -1292,7 +1496,7 @@ pair. You can retrieve the value with .get() without generating an exception, li
 ```c++
 ondemand::document doc;
 auto error = parser.iterate(json).get(doc);
-if (error) { cerr << error << endl; exit(1); }
+if(error) { std::cerr << simdjson::error_message(error); exit(1); }
 ```
 
 When there is no error, the error code `simdjson::SUCCESS`is returned: it evaluates as false as a Boolean.
@@ -1323,7 +1527,7 @@ bool simple_error_example() {
     auto error = doc["bad number"].get_double().get(x);
     // returns "simdjson::NUMBER_ERROR"
     if (error != SUCCESS) {
-      std::cout << error << std::endl;
+      std::cerr << simdjson::error_message(error) << std::endl;
       return false;
     }
     std::cout << "Got " << x << std::endl;
@@ -1357,7 +1561,7 @@ Notice how we can retrieve the exact error condition (in this instance `simdjson
 from the exception.
 
 We can write a "quick start" example where we attempt to parse the following JSON file and access some data, without triggering exceptions:
-```JavaScript
+```JSON
 {
   "statuses": [
     {
@@ -1376,7 +1580,6 @@ 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++
 #include <iostream>
 #include "simdjson.h"
@@ -1384,10 +1587,10 @@ it selects the key `"count"` within that object.
 int main(void) {
   simdjson::ondemand::parser parser;
   auto error = padded_string::load("twitter.json").get(json);
-  if (error) { std::cerr << error << std::endl; return EXIT_FAILURE; }
+  if (error) { std::cerr << simdjson::error_message(error) << std::endl; return EXIT_FAILURE; }
   simdjson::ondemand::document tweets;
   error = parser.iterate(json).get(tweets);
-  if (error) { std::cerr << error << std::endl; return EXIT_FAILURE; }
+  if (error) { std::cerr << simdjson::error_message(error) << std::endl; return EXIT_FAILURE; }
   simdjson::ondemand::value res;
   error = tweets["search_metadata"]["count"].get(res);
   if (error != SUCCESS) {
@@ -1418,12 +1621,12 @@ int main(void) {
   simdjson::ondemand::document tweets;
   padded_string json;
   auto error = padded_string::load("twitter.json").get(json);
-  if (error) { std::cerr << error << std::endl; return EXIT_FAILURE; }
+  if (error) { std::cerr << simdjson::error_message(error) << std::endl; return EXIT_FAILURE; }
   error = parser.iterate(json).get(tweets);
-  if (error) { std::cerr << error << std::endl; return EXIT_FAILURE; }
+  if (error) { std::cerr << simdjson::error_message(error) << std::endl; return EXIT_FAILURE; }
   uint64_t identifier;
   error = tweets["statuses"].at(0)["id"].get(identifier);
-  if (error) { std::cerr << error << std::endl; return EXIT_FAILURE; }
+  if (error) { std::cerr << simdjson::error_message(error) << std::endl; return EXIT_FAILURE; }
   std::cout << identifier << std::endl;
 }
 ```
@@ -1447,40 +1650,40 @@ bool parse() {
 
   // Iterating through an array of objects
   auto error = parser.iterate(cars_json).get(doc);
-  if (error) { std::cerr << error << std::endl; return false; }
+  if (error) { std::cerr << simdjson::error_message(error) << std::endl; return false; }
   ondemand::array cars; // invalid until the get() succeeds
   error = doc.get_array().get(cars);
 
   for (auto car_value : cars) {
     ondemand::object car; // invalid until the get() succeeds
     error = car_value.get_object().get(car);
-    if (error) { std::cerr << error << std::endl; return false; }
+    if (error) { std::cerr << simdjson::error_message(error) << std::endl; return false; }
 
     // Accessing a field by name
     std::string_view make;
     std::string_view model;
     error = car["make"].get(make);
-    if (error) { std::cerr << error << std::endl; return false; }
+    if (error) { std::cerr << simdjson::error_message(error) << std::endl; return false; }
     error = car["model"].get(model);
-    if (error) { std::cerr << error << std::endl; return false; }
+    if (error) { std::cerr << simdjson::error_message(error) << std::endl; return false; }
 
     cout << "Make/Model: " << make << "/" << model << endl;
 
     // Casting a JSON element to an integer
     uint64_t year{};
     error = car["year"].get(year);
-    if (error) { std::cerr << error << std::endl; return false; }
+    if (error) { std::cerr << simdjson::error_message(error) << std::endl; return false; }
     cout << "- This car is " << 2020 - year << " years old." << endl;
 
     // Iterating through an array of floats
     double total_tire_pressure = 0;
     ondemand::array pressures;
     error = car["tire_pressure"].get_array().get(pressures);
-    if (error) { std::cerr << error << std::endl; return false; }
+    if (error) { std::cerr << simdjson::error_message(error) << std::endl; return false; }
     for (auto tire_pressure_value : pressures) {
       double tire_pressure;
       error = tire_pressure_value.get_double().get(tire_pressure);
-      if (error) { std::cerr << error << std::endl; return false; }
+      if (error) { std::cerr << simdjson::error_message(error) << std::endl; return false; }
       total_tire_pressure += tire_pressure;
     }
     cout << "- Average tire pressure: " << (total_tire_pressure / 4) << endl;
@@ -1602,7 +1805,7 @@ auto doc = parser.iterate(broken_json);
 int64_t i;
 auto error = doc["integer"].get_int64().get(i);    // Expect to get integer from "integer" key, but get TAPE_ERROR
 if (error) {
-  std::cout << error << std::endl;    // Prints TAPE_ERROR error message
+  std::cerr << simdjson::error_message(error) << std::endl;    // Prints TAPE_ERROR error message
   // Recover a pointer to the location of the first error:
   const char * ptr;
   doc.current_location().get(ptr);
@@ -1639,7 +1842,7 @@ auto doc = parser.iterate(json);
 int64_t i;
 auto error = doc["integer"].get_int64().get(i);    // Incorrect call on array, INCORRECT_TYPE error
 if (error) {
-  std::cout << error << std::endl;     // Prints INCORRECT_TYPE error message
+  std::cerr << simdjson::error_message(error) << std::endl;     // Prints INCORRECT_TYPE error message
   std::cout<< doc.current_location() << std::endl;  // Prints "[1,2,3] " (location of INCORRECT_TYPE error)
 }
 ```
@@ -1812,7 +2015,7 @@ for (auto doc: stream) {
     error = doc.at_pointer("/4").get(val);
     // error == simdjson::CAPACITY
     if (error) {
-      std::cerr << error << std::endl;
+      std::cerr << simdjson::error_message(error) << std::endl;
       // We left 293 bytes unprocessed at the tail end of the input.
       std::cout << " unprocessed bytes at the end: " << stream.truncated_bytes() << std::endl;
       break;

doc/iterate_many.md

@@ -25,6 +25,7 @@ Contents
 - [Use cases](#use-cases)
 - [Tracking your position](#tracking-your-position)
 - [Incomplete streams](#incomplete-streams)
+- [C++20 features](#c20-features)
 
 Motivation
 -----------
@@ -293,3 +294,111 @@ string
 object
 array
 ```
+
+
+C++20 features
+--------------------
+
+In C++20, the standard introduced the notion of *customization point*.
+A customization point is a function or function object that can be customized for different types. It allows library authors to provide default behavior while giving users the ability to override this behavior for specific types.
+
+A tag_invoke function serves as a mechanism for customization points. It is not directly part of the C++ standard library but is often used in libraries that implement customization points.
+The tag_invoke function is typically a generic function that takes a tag type and additional arguments.
+The first argument is usually a tag type (often an empty struct) that uniquely identifies the customization point (e.g., deserialization of custom types in simdjson). Users or library providers can specialize tag_invoke for their types by defining it in the appropriate namespace, often inline namespace.
+
+
+
+You can deserialize you own data structures conveniently if your system supports C++20.
+When it is the case, the macro `SIMDJSON_SUPPORTS_DESERIALIZATION` will be set to 1 by
+the simdjson library.
+
+Consider a custom class `Car`:
+
+```C++
+struct Car {
+  std::string make;
+  std::string model;
+  int year;
+  std::vector<float> tire_pressure;
+};
+```
+
+
+You may support deserializing directly from a JSON value or document to your own `Car` instance
+by defining a single `tag_invoke` function:
+
+
+```C++
+namespace simdjson {
+// This tag_invoke MUST be inside simdjson namespace
+template <typename simdjson_value>
+auto tag_invoke(deserialize_tag, simdjson_value &val, Car& car) {
+  ondemand::object obj;
+  auto error = val.get_object().get(obj);
+  if (error) {
+    return error;
+  }
+  if ((error = obj["make"].get_string(car.make))) {
+    return error;
+  }
+  if ((error = obj["model"].get_string(car.model))) {
+    return error;
+  }
+  if ((error = obj["year"].get(car.year))) {
+    return error;
+  }
+  if ((error = obj["tire_pressure"].get<std::vector<float>>().get(
+           car.tire_pressure))) {
+    return error;
+  }
+  return simdjson::SUCCESS;
+}
+} // namespace simdjson
+```
+
+Importantly, the `tag_invoke` function must be inside the `simdjson` namespace.
+Let us explain each argument of `tag_invoke` function.
+
+- `simdjson::deserialize_tag`: it is the tag for Customization Point Object (CPO). You may often ignore this parameter. It is used to indicate that you mean to provide a deserialization function for simdjson.
+- `var`: It receives automatically a `simdjson` value type (document, value, document_reference).
+- The third parameter is an instance of the type that you want to support.
+
+Please see our main documentation (`basics.md`) under
+"Use `tag_invoke` for custom types (C++20)" for details about
+tag_invoke functions.
+
+Given a stream of JSON documents, you can add them to a data struture
+such as a `std::vector<Car>` like so if you support exceptions:
+
+```C++
+  padded_string json =
+      R"( { "make": "Toyota", "model": "Camry",  "year": 2018,
+       "tire_pressure": [ 40.1, 39.9 ] }
+  { "make": "Kia",    "model": "Soul",   "year": 2012,
+       "tire_pressure": [ 30.1, 31.0 ] }
+  { "make": "Toyota", "model": "Tercel", "year": 1999,
+       "tire_pressure": [ 29.8, 30.0 ] }
+)"_padded;
+  ondemand::parser parser;
+  ondemand::document_stream stream;
+  [[maybe_unused]] auto error = parser.iterate_many(json).get(stream);
+  std::vector<Car> cars;
+  for(auto doc : stream) {
+    cars.push_back((Car)doc); // an exception may be thrown
+  }
+```
+
+Otherwise you may use this longer version for explicit handling of errors:
+
+
+```C++
+  std::vector<Car> cars;
+  for(auto doc : stream) {
+    Car c;
+    if ((error = doc.get<Car>().get(c))) {
+      std::cerr << simdjson::error_message(error); << std::endl;
+      return EXIT_FAILURE;
+    }
+    cars.push_back(c);
+  }
+```

include/simdjson.h

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

include/simdjson/arm64/implementation.h

@@ -23,6 +23,7 @@ public:
   ) const noexcept final;
   simdjson_warn_unused error_code minify(const uint8_t *buf, size_t len, uint8_t *dst, size_t &dst_len) const noexcept final;
   simdjson_warn_unused bool validate_utf8(const char *buf, size_t len) const noexcept final;
+  simdjson_warn_unused size_t write_string_escaped(const std::string_view input, char *out) const noexcept final;
 };
 
 } // namespace arm64

include/simdjson/arm64/simd.h

@@ -134,6 +134,12 @@ namespace {
       tmp = vpaddq_u8(tmp, tmp);
       return vgetq_lane_u16(vreinterpretq_u16_u8(tmp), 0);
     }
+    // Returns 4-bit out of each byte, alternating between the high 4 bits and low
+    // bits result it is 64 bit.
+    simdjson_inline uint64_t to_bitmask64() const {
+      return vget_lane_u64(
+          vreinterpret_u64_u8(vshrn_n_u16(vreinterpretq_u16_u8(*this), 4)), 0);
+    }
     simdjson_inline bool any() const { return vmaxvq_u32(vreinterpretq_u32_u8(*this)) != 0; }
   };
 
@@ -210,7 +216,7 @@ namespace {
 
     // Bit-specific operations
     simdjson_inline simd8<bool> any_bits_set(simd8<uint8_t> bits) const { return vtstq_u8(*this, bits); }
-    simdjson_inline bool any_bits_set_anywhere() const { return this->max_val() != 0; }
+    simdjson_inline bool any_bits_set_anywhere() const { return vmaxvq_u32(vreinterpretq_u32_u8(*this)) != 0; }
     simdjson_inline bool any_bits_set_anywhere(simd8<uint8_t> bits) const { return (*this & bits).any_bits_set_anywhere(); }
     template<int N>
     simdjson_inline simd8<uint8_t> shr() const { return vshrq_n_u8(*this, N); }
@@ -223,7 +229,12 @@ namespace {
       return lookup_table.apply_lookup_16_to(*this);
     }
 
-
+    // Returns 4-bit out of each byte, alternating between the high 4 bits and low
+    // bits result it is 64 bit.
+    simdjson_inline uint64_t to_bitmask64() const {
+      return vget_lane_u64(
+          vreinterpret_u64_u8(vshrn_n_u16(vreinterpretq_u16_u8(*this), 4)), 0);
+    }
     // Copies to 'output" all bytes corresponding to a 0 in the mask (interpreted as a bitset).
     // Passing a 0 value for mask would be equivalent to writing out every byte to output.
     // Only the first 16 - count_ones(mask) bytes of the result are significant but 16 bytes

include/simdjson/arm64/stringparsing_defs.h

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

include/simdjson/base.h

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

include/simdjson/compiler_check.h

@@ -50,4 +50,16 @@
 #endif
 #endif
 
+#ifdef __has_include
+#if __has_include(<version>)
+#include <version>
+#endif
+#endif
+
+#ifdef __cpp_concepts
+#include <utility>
+#define SIMDJSON_SUPPORTS_DESERIALIZATION 1
+#else // __cpp_concepts
+#define SIMDJSON_SUPPORTS_DESERIALIZATION 0
+#endif
 #endif // SIMDJSON_COMPILER_CHECK_H

include/simdjson/concepts.h

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

include/simdjson/error.h

@@ -49,7 +49,8 @@ enum error_code {
   SCALAR_DOCUMENT_AS_VALUE,   ///< A scalar document is treated as a value.
   OUT_OF_BOUNDS,              ///< Attempted to access location outside of document.
   TRAILING_CONTENT,           ///< Unexpected trailing content in the JSON input
-  NUM_ERROR_CODES
+  OUT_OF_CAPACITY,            ///< The capacity was exceeded, we cannot allocate enough memory.
+  NUM_ERROR_CODES             ///< Placeholder for end of error code list.
 };
 
 /**

include/simdjson/fallback/implementation.h

@@ -26,6 +26,7 @@ public:
   ) const noexcept final;
   simdjson_warn_unused error_code minify(const uint8_t *buf, size_t len, uint8_t *dst, size_t &dst_len) const noexcept final;
   simdjson_warn_unused bool validate_utf8(const char *buf, size_t len) const noexcept final;
+  simdjson_warn_unused size_t write_string_escaped(const std::string_view input, char *out) const noexcept final;
 };
 
 } // namespace fallback

include/simdjson/fallback/stringparsing_defs.h

@@ -29,6 +29,24 @@ simdjson_inline backslash_and_quote backslash_and_quote::copy_and_find(const uin
   return { src[0] };
 }
 
+
+struct escaping {
+  static constexpr uint32_t BYTES_PROCESSED = 1;
+  simdjson_inline static escaping copy_and_find(const uint8_t *src, uint8_t *dst);
+
+  simdjson_inline bool has_escape() { return escape_bits; }
+  simdjson_inline int escape_index() { return 0; }
+
+  bool escape_bits;
+}; // struct escaping
+
+
+
+simdjson_inline escaping escaping::copy_and_find(const uint8_t *src, uint8_t *dst) {
+  dst[0] = src[0];
+  return { (src[0] == '\\') || (src[0] == '"') || (src[0] < 32) };
+}
+
 } // unnamed namespace
 } // namespace fallback
 } // namespace simdjson

include/simdjson/generic/dependencies.h

@@ -16,5 +16,4 @@
 #include "simdjson/internal/jsoncharutils_tables.h"
 #include "simdjson/internal/numberparsing_tables.h"
 #include "simdjson/internal/simdprune_tables.h"
-
 #endif // SIMDJSON_GENERIC_DEPENDENCIES_H

include/simdjson/generic/ondemand/amalgamated.h

@@ -4,6 +4,7 @@
 
 // Stuff other things depend on
 #include "simdjson/generic/ondemand/base.h"
+#include "simdjson/generic/ondemand/deserialize.h"
 #include "simdjson/generic/ondemand/value_iterator.h"
 #include "simdjson/generic/ondemand/value.h"
 #include "simdjson/generic/ondemand/logger.h"
@@ -23,9 +24,13 @@
 #include "simdjson/generic/ondemand/object_iterator.h"
 #include "simdjson/generic/ondemand/serialization.h"
 
+// Deserialization for standard types
+#include "simdjson/generic/ondemand/std_deserialize.h"
+
 // Inline definitions
 #include "simdjson/generic/ondemand/array-inl.h"
 #include "simdjson/generic/ondemand/array_iterator-inl.h"
+#include "simdjson/generic/ondemand/value-inl.h"
 #include "simdjson/generic/ondemand/document-inl.h"
 #include "simdjson/generic/ondemand/document_stream-inl.h"
 #include "simdjson/generic/ondemand/field-inl.h"
@@ -38,5 +43,10 @@
 #include "simdjson/generic/ondemand/raw_json_string-inl.h"
 #include "simdjson/generic/ondemand/serialization-inl.h"
 #include "simdjson/generic/ondemand/token_iterator-inl.h"
-#include "simdjson/generic/ondemand/value-inl.h"
 #include "simdjson/generic/ondemand/value_iterator-inl.h"
+
+// JSON builder, ideally they should not be part of the ondemand directory
+// but it is convenient for now to have them here.
+#include "simdjson/generic/ondemand/json_string_builder.h"
+#include "simdjson/generic/ondemand/json_string_builder-inl.h"
+

include/simdjson/generic/ondemand/deserialize.h

@@ -0,0 +1,123 @@
+#if SIMDJSON_SUPPORTS_DESERIALIZATION
+
+#ifndef SIMDJSON_ONDEMAND_DESERIALIZE_H
+#ifndef SIMDJSON_CONDITIONAL_INCLUDE
+#define SIMDJSON_ONDEMAND_DESERIALIZE_H
+#include "simdjson/generic/ondemand/base.h"
+#include "simdjson/generic/ondemand/array.h"
+#endif // SIMDJSON_CONDITIONAL_INCLUDE
+
+#include <concepts>
+namespace simdjson {
+
+namespace tag_invoke_fn_ns {
+void tag_invoke();
+
+struct tag_invoke_fn {
+  template <typename Tag, typename... Args>
+    requires requires(Tag tag, Args &&...args) {
+      tag_invoke(std::forward<Tag>(tag), std::forward<Args>(args)...);
+    }
+  constexpr auto operator()(Tag tag, Args &&...args) const
+      noexcept(noexcept(tag_invoke(std::forward<Tag>(tag),
+                                   std::forward<Args>(args)...)))
+          -> decltype(tag_invoke(std::forward<Tag>(tag),
+                                 std::forward<Args>(args)...)) {
+    return tag_invoke(std::forward<Tag>(tag), std::forward<Args>(args)...);
+  }
+};
+} // namespace tag_invoke_fn_ns
+
+inline namespace tag_invoke_ns {
+inline constexpr tag_invoke_fn_ns::tag_invoke_fn tag_invoke = {};
+} // namespace tag_invoke_ns
+
+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;
+    };
+
+template <typename Tag, typename... Args>
+using tag_invoke_result =
+    std::invoke_result<decltype(tag_invoke), Tag, Args...>;
+
+template <typename Tag, typename... Args>
+using tag_invoke_result_t =
+    std::invoke_result_t<decltype(tag_invoke), Tag, Args...>;
+
+template <auto &Tag> using tag_t = std::decay_t<decltype(Tag)>;
+
+
+struct deserialize_tag;
+
+/// These types are deserializable in a built-in way
+template <typename> struct is_builtin_deserializable : std::false_type {};
+template <> struct is_builtin_deserializable<int64_t> : std::true_type {};
+template <> struct is_builtin_deserializable<uint64_t> : std::true_type {};
+template <> struct is_builtin_deserializable<double> : std::true_type {};
+template <> struct is_builtin_deserializable<bool> : std::true_type {};
+template <> struct is_builtin_deserializable<SIMDJSON_IMPLEMENTATION::ondemand::array> : std::true_type {};
+template <> struct is_builtin_deserializable<SIMDJSON_IMPLEMENTATION::ondemand::object> : std::true_type {};
+template <> struct is_builtin_deserializable<SIMDJSON_IMPLEMENTATION::ondemand::value> : std::true_type {};
+template <> struct is_builtin_deserializable<SIMDJSON_IMPLEMENTATION::ondemand::raw_json_string> : std::true_type {};
+template <> struct is_builtin_deserializable<std::string_view> : std::true_type {};
+
+template <typename T>
+concept is_builtin_deserializable_v = is_builtin_deserializable<T>::value;
+
+template <typename T, typename ValT = SIMDJSON_IMPLEMENTATION::ondemand::value>
+concept custom_deserializable = tag_invocable<deserialize_tag, ValT&, T&>;
+
+template <typename T, typename ValT = SIMDJSON_IMPLEMENTATION::ondemand::value>
+concept deserializable = custom_deserializable<T, ValT> || is_builtin_deserializable_v<T>;
+
+template <typename T, typename ValT = SIMDJSON_IMPLEMENTATION::ondemand::value>
+concept nothrow_custom_deserializable = nothrow_tag_invocable<deserialize_tag, ValT&, T&>;
+
+// built-in types are noexcept and if an error happens, the value simply gets ignored and the error is returned.
+template <typename T, typename ValT = SIMDJSON_IMPLEMENTATION::ondemand::value>
+concept nothrow_deserializable = nothrow_custom_deserializable<T, ValT> || is_builtin_deserializable_v<T>;
+
+/// Deserialize Tag
+inline constexpr struct deserialize_tag {
+  using value_type = SIMDJSON_IMPLEMENTATION::ondemand::value;
+  using document_type = SIMDJSON_IMPLEMENTATION::ondemand::document;
+  using document_reference_type = SIMDJSON_IMPLEMENTATION::ondemand::document_reference;
+
+  // Customization Point for value
+  template <typename T>
+    requires custom_deserializable<T, value_type>
+  [[nodiscard]] constexpr /* error_code */ auto operator()(value_type &object, T& output) const noexcept(nothrow_custom_deserializable<T, value_type>) {
+    return tag_invoke(*this, object, output);
+  }
+
+  // Customization Point for document
+  template <typename T>
+    requires custom_deserializable<T, document_type>
+  [[nodiscard]] constexpr /* error_code */ auto operator()(document_type &object, T& output) const noexcept(nothrow_custom_deserializable<T, document_type>) {
+    return tag_invoke(*this, object, output);
+  }
+
+  // Customization Point for document reference
+  template <typename T>
+    requires custom_deserializable<T, document_reference_type>
+  [[nodiscard]] constexpr /* error_code */ auto operator()(document_reference_type &object, T& output) const noexcept(nothrow_custom_deserializable<T, document_reference_type>) {
+    return tag_invoke(*this, object, output);
+  }
+
+
+} deserialize{};
+
+} // namespace simdjson
+
+#endif // SIMDJSON_ONDEMAND_DESERIALIZE_H
+#endif // SIMDJSON_SUPPORTS_DESERIALIZATION
+

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

@@ -8,10 +8,12 @@
 #include "simdjson/generic/ondemand/json_type.h"
 #include "simdjson/generic/ondemand/raw_json_string.h"
 #include "simdjson/generic/ondemand/value.h"
+#include "simdjson/generic/ondemand/value-inl.h"
 #include "simdjson/generic/ondemand/array-inl.h"
 #include "simdjson/generic/ondemand/json_iterator-inl.h"
 #include "simdjson/generic/ondemand/object-inl.h"
 #include "simdjson/generic/ondemand/value_iterator-inl.h"
+#include "simdjson/generic/ondemand/deserialize.h"
 #endif // SIMDJSON_CONDITIONAL_INCLUDE
 
 namespace simdjson {
@@ -165,6 +167,16 @@ template<> simdjson_inline simdjson_result<int64_t> document::get() & noexcept {
 template<> simdjson_inline simdjson_result<bool> document::get() & noexcept { return get_bool(); }
 template<> simdjson_inline simdjson_result<value> document::get() & noexcept { return get_value(); }
 
+template<> simdjson_inline error_code document::get(array& out) & noexcept { return get_array().get(out); }
+template<> simdjson_inline error_code document::get(object& out) & noexcept { return get_object().get(out); }
+template<> simdjson_inline error_code document::get(raw_json_string& out) & noexcept { return get_raw_json_string().get(out); }
+template<> simdjson_inline error_code document::get(std::string_view& out) & noexcept { return get_string(false).get(out); }
+template<> simdjson_inline error_code document::get(double& out) & noexcept { return get_double().get(out); }
+template<> simdjson_inline error_code document::get(uint64_t& out) & noexcept { return get_uint64().get(out); }
+template<> simdjson_inline error_code document::get(int64_t& out) & noexcept { return get_int64().get(out); }
+template<> simdjson_inline error_code document::get(bool& out) & noexcept { return get_bool().get(out); }
+template<> simdjson_inline error_code document::get(value& out) & noexcept { return get_value().get(out); }
+
 template<> simdjson_deprecated simdjson_inline simdjson_result<raw_json_string> document::get() && noexcept { return get_raw_json_string(); }
 template<> simdjson_deprecated simdjson_inline simdjson_result<std::string_view> document::get() && noexcept { return get_string(false); }
 template<> simdjson_deprecated simdjson_inline simdjson_result<double> document::get() && noexcept { return std::forward<document>(*this).get_double(); }
@@ -173,13 +185,6 @@ template<> simdjson_deprecated simdjson_inline simdjson_result<int64_t> document
 template<> simdjson_deprecated simdjson_inline simdjson_result<bool> document::get() && noexcept { return std::forward<document>(*this).get_bool(); }
 template<> simdjson_deprecated simdjson_inline simdjson_result<value> document::get() && noexcept { return get_value(); }
 
-template<typename T> simdjson_inline error_code document::get(T &out) & noexcept {
-  return get<T>().get(out);
-}
-template<typename T> simdjson_deprecated simdjson_inline error_code document::get(T &out) && noexcept {
-  return std::forward<document>(*this).get<T>().get(out);
-}
-
 #if SIMDJSON_EXCEPTIONS
 template <class T>
 simdjson_deprecated simdjson_inline document::operator T() && noexcept(false) { return get<T>(); }
@@ -818,6 +823,26 @@ simdjson_inline simdjson_result<bool> simdjson_result<SIMDJSON_IMPLEMENTATION::o
   if (error()) { return error(); }
   return first.is_null();
 }
+template<typename T>
+simdjson_inline simdjson_result<T> simdjson_result<SIMDJSON_IMPLEMENTATION::ondemand::document_reference>::get() & noexcept {
+  if (error()) { return error(); }
+  return first.get<T>();
+}
+template<typename T>
+simdjson_inline simdjson_result<T> simdjson_result<SIMDJSON_IMPLEMENTATION::ondemand::document_reference>::get() && noexcept {
+  if (error()) { return error(); }
+  return std::forward<SIMDJSON_IMPLEMENTATION::ondemand::document_reference>(first).get<T>();
+}
+template <class T>
+simdjson_inline error_code simdjson_result<SIMDJSON_IMPLEMENTATION::ondemand::document_reference>::get(T &out) & noexcept {
+  if (error()) { return error(); }
+  return first.get<T>(out);
+}
+template <class T>
+simdjson_inline error_code simdjson_result<SIMDJSON_IMPLEMENTATION::ondemand::document_reference>::get(T &out) && noexcept {
+  if (error()) { return error(); }
+  return std::forward<SIMDJSON_IMPLEMENTATION::ondemand::document_reference>(first).get<T>(out);
+}
 simdjson_inline simdjson_result<SIMDJSON_IMPLEMENTATION::ondemand::json_type> simdjson_result<SIMDJSON_IMPLEMENTATION::ondemand::document_reference>::type() noexcept {
   if (error()) { return error(); }
   return first.type();
@@ -830,6 +855,18 @@ simdjson_inline simdjson_result<bool> simdjson_result<SIMDJSON_IMPLEMENTATION::o
   if (error()) { return error(); }
   return first.is_string();
 }
+template <>
+simdjson_inline error_code simdjson_result<SIMDJSON_IMPLEMENTATION::ondemand::document_reference>::get(SIMDJSON_IMPLEMENTATION::ondemand::document_reference &out) & noexcept {
+  if (error()) { return error(); }
+  out = first;
+  return SUCCESS;
+}
+template <>
+simdjson_inline error_code simdjson_result<SIMDJSON_IMPLEMENTATION::ondemand::document_reference>::get(SIMDJSON_IMPLEMENTATION::ondemand::document_reference &out) && noexcept {
+  if (error()) { return error(); }
+  out = first;
+  return SUCCESS;
+}
 simdjson_inline simdjson_result<bool> simdjson_result<SIMDJSON_IMPLEMENTATION::ondemand::document_reference>::is_negative() noexcept {
   if (error()) { return error(); }
   return first.is_negative();
@@ -847,10 +884,12 @@ simdjson_inline simdjson_result<SIMDJSON_IMPLEMENTATION::ondemand::number> simdj
   return first.get_number();
 }
 #if SIMDJSON_EXCEPTIONS
-template <class T, typename std::enable_if<std::is_same<T, SIMDJSON_IMPLEMENTATION::ondemand::document_reference>::value == false>::type>
+template <class T>
 simdjson_inline simdjson_result<SIMDJSON_IMPLEMENTATION::ondemand::document_reference>::operator T() noexcept(false) {
+  static_assert(std::is_same<T, SIMDJSON_IMPLEMENTATION::ondemand::document_reference>::value == false, "You should not call get<T> when T is a document");
+  static_assert(std::is_same<T, SIMDJSON_IMPLEMENTATION::ondemand::document>::value == false, "You should not call get<T> when T is a document");
   if (error()) { throw simdjson_error(error()); }
-  return first;
+  return first.get<T>();
 }
 simdjson_inline simdjson_result<SIMDJSON_IMPLEMENTATION::ondemand::document_reference>::operator SIMDJSON_IMPLEMENTATION::ondemand::array() & noexcept(false) {
   if (error()) { throw simdjson_error(error()); }

include/simdjson/generic/ondemand/document.h

@@ -4,8 +4,11 @@
 #define SIMDJSON_GENERIC_ONDEMAND_DOCUMENT_H
 #include "simdjson/generic/ondemand/base.h"
 #include "simdjson/generic/ondemand/json_iterator.h"
+#include "simdjson/generic/ondemand/deserialize.h"
+#include "simdjson/generic/ondemand/value.h"
 #endif // SIMDJSON_CONDITIONAL_INCLUDE
 
+
 namespace simdjson {
 namespace SIMDJSON_IMPLEMENTATION {
 namespace ondemand {
@@ -178,24 +181,39 @@ public:
    * @returns A value of the given type, parsed from the JSON.
    * @returns INCORRECT_TYPE If the JSON value is not the given type.
    */
-  template<typename T> simdjson_inline simdjson_result<T> get() & noexcept {
+  template <typename T>
-    // Unless the simdjson library or the user provides an inline implementation, calling this method should
+  simdjson_inline simdjson_result<T> get() &
-    // immediately fail.
+#if SIMDJSON_SUPPORTS_DESERIALIZATION
-    static_assert(!sizeof(T), "The get method with given type is not implemented by the simdjson library. "
+    noexcept(custom_deserializable<T, document> ? nothrow_custom_deserializable<T, document> : true)
-      "The supported types are ondemand::object, ondemand::array, raw_json_string, std::string_view, uint64_t, "
+#else
-      "int64_t, double, and bool. We recommend you use get_double(), get_bool(), get_uint64(), get_int64(), "
+    noexcept
-      " get_object(), get_array(), get_raw_json_string(), or get_string() instead of the get template."
+#endif
-      " You may also add support for custom types, see our documentation.");
+  {
+    static_assert(std::is_default_constructible<T>::value, "Cannot initialize the specified type.");
+    T out{};
+    SIMDJSON_TRY(get<T>(out));
+    return out;
   }
-  /** @overload template<typename T> simdjson_result<T> get() & noexcept */
+  /**
-  template<typename T> simdjson_deprecated simdjson_inline simdjson_result<T> get() && noexcept {
+   * @overload template<typename T> simdjson_result<T> get() & noexcept
-    // Unless the simdjson library or the user provides an inline implementation, calling this method should
+   *
-    // immediately fail.
+   * We disallow the use tag_invoke CPO on a moved document; it may create UB
-    static_assert(!sizeof(T), "The get method with given type is not implemented by the simdjson library. "
+   * if user uses `ondemand::array` or `ondemand::object` in their custom type.
-      "The supported types are ondemand::object, ondemand::array, raw_json_string, std::string_view, uint64_t, "
+   *
-      "int64_t, double, and bool. We recommend you use get_double(), get_bool(), get_uint64(), get_int64(), "
+   * The member function is still remains specialize-able for compatibility
-      " get_object(), get_array(), get_raw_json_string(), or get_string() instead of the get template."
+   * reasons, but we completely disallow its use when a tag_invoke customization
-      " You may also add support for custom types, see our documentation.");
+   * is provided.
+   */
+  template<typename T>
+  simdjson_inline simdjson_result<T> get() &&
+#if SIMDJSON_SUPPORTS_DESERIALIZATION
+    noexcept(custom_deserializable<T, document> ? nothrow_custom_deserializable<T, document> : true)
+#else
+    noexcept
+#endif
+  {
+      static_assert(!std::is_same<T, array>::value && !std::is_same<T, object>::value, "You should never hold either an ondemand::array or ondemand::object without a corresponding ondemand::document being alive; that would be Undefined Behaviour.");
+      return static_cast<document&>(*this).get<T>();
   }
 
   /**
@@ -209,7 +227,32 @@ public:
    * @returns INCORRECT_TYPE If the JSON value is not an object.
    * @returns SUCCESS If the parse succeeded and the out parameter was set to the value.
    */
-  template<typename T> simdjson_inline error_code get(T &out) & noexcept;
+  template<typename T>
+  simdjson_inline error_code get(T &out) &
+#if SIMDJSON_SUPPORTS_DESERIALIZATION
+    noexcept(custom_deserializable<T, document> ? nothrow_custom_deserializable<T, document> : true)
+#else
+    noexcept
+#endif
+  {
+#if SIMDJSON_SUPPORTS_DESERIALIZATION
+    if constexpr (custom_deserializable<T, document>) {
+        return deserialize(*this, out);
+    } else {
+#endif // SIMDJSON_SUPPORTS_DESERIALIZATION
+      // Unless the simdjson library or the user provides an inline implementation, calling this method should
+      // immediately fail.
+      static_assert(!sizeof(T), "The get method with given type is not implemented by the simdjson library. "
+        "The supported types are ondemand::object, ondemand::array, raw_json_string, std::string_view, uint64_t, "
+        "int64_t, double, and bool. We recommend you use get_double(), get_bool(), get_uint64(), get_int64(), "
+        " get_object(), get_array(), get_raw_json_string(), or get_string() instead of the get template."
+        " You may also add support for custom types, see our documentation.");
+      static_cast<void>(out); // to get rid of unused errors
+      return UNINITIALIZED;
+#if SIMDJSON_SUPPORTS_DESERIALIZATION
+    }
+#endif
+  }
   /** @overload template<typename T> error_code get(T &out) & noexcept */
   template<typename T> simdjson_deprecated simdjson_inline error_code get(T &out) && noexcept;
 
@@ -721,7 +764,70 @@ public:
   simdjson_inline simdjson_result<value> get_value() noexcept;
 
   simdjson_inline simdjson_result<bool> is_null() noexcept;
-  template<typename T> simdjson_inline simdjson_result<T> get() & noexcept;
+  template <typename T>
+  simdjson_inline simdjson_result<T> get() &
+#if SIMDJSON_SUPPORTS_DESERIALIZATION
+    noexcept(custom_deserializable<T, document> ? nothrow_custom_deserializable<T, document> : true)
+#else
+    noexcept
+#endif
+  {
+    static_assert(std::is_default_constructible<T>::value, "Cannot initialize the specified type.");
+    T out{};
+    SIMDJSON_TRY(get<T>(out));
+    return out;
+  }
+  template<typename T>
+  simdjson_inline simdjson_result<T> get() &&
+#if SIMDJSON_SUPPORTS_DESERIALIZATION
+    noexcept(custom_deserializable<T, document> ? nothrow_custom_deserializable<T, document> : true)
+#else
+    noexcept
+#endif
+  {
+      static_assert(!std::is_same<T, array>::value && !std::is_same<T, object>::value, "You should never hold either an ondemand::array or ondemand::object without a corresponding ondemand::document_reference being alive; that would be Undefined Behaviour.");
+      return static_cast<document&>(*this).get<T>();
+  }
+
+  /**
+   * Get this value as the given type.
+   *
+   * Supported types: object, array, raw_json_string, string_view, uint64_t, int64_t, double, bool, value
+   *
+   * Be mindful that the document instance must remain in scope while you are accessing object, array and value instances.
+   *
+   * @param out This is set to a value of the given type, parsed from the JSON. If there is an error, this may not be initialized.
+   * @returns INCORRECT_TYPE If the JSON value is not an object.
+   * @returns SUCCESS If the parse succeeded and the out parameter was set to the value.
+   */
+  template<typename T>
+  simdjson_inline error_code get(T &out) &
+#if SIMDJSON_SUPPORTS_DESERIALIZATION
+    noexcept(custom_deserializable<T, document> ? nothrow_custom_deserializable<T, document_reference> : true)
+#else
+    noexcept
+#endif
+  {
+#if SIMDJSON_SUPPORTS_DESERIALIZATION
+    if constexpr (custom_deserializable<T, document_reference>) {
+        return deserialize(*this, out);
+    } else {
+#endif // SIMDJSON_SUPPORTS_DESERIALIZATION
+      // Unless the simdjson library or the user provides an inline implementation, calling this method should
+      // immediately fail.
+      static_assert(!sizeof(T), "The get method with given type is not implemented by the simdjson library. "
+        "The supported types are ondemand::object, ondemand::array, raw_json_string, std::string_view, uint64_t, "
+        "int64_t, double, and bool. We recommend you use get_double(), get_bool(), get_uint64(), get_int64(), "
+        " get_object(), get_array(), get_raw_json_string(), or get_string() instead of the get template."
+        " You may also add support for custom types, see our documentation.");
+      static_cast<void>(out); // to get rid of unused errors
+      return UNINITIALIZED;
+#if SIMDJSON_SUPPORTS_DESERIALIZATION
+    }
+#endif
+  }
+  /** @overload template<typename T> error_code get(T &out) & noexcept */
+  template<typename T> simdjson_inline error_code get(T &out) && noexcept;
   simdjson_inline simdjson_result<std::string_view> raw_json() noexcept;
   simdjson_inline operator document&() const noexcept;
 #if SIMDJSON_EXCEPTIONS
@@ -873,8 +979,14 @@ public:
   simdjson_inline simdjson_result<bool> get_bool() noexcept;
   simdjson_inline simdjson_result<SIMDJSON_IMPLEMENTATION::ondemand::value> get_value() noexcept;
   simdjson_inline simdjson_result<bool> is_null() noexcept;
+
+  template<typename T> simdjson_inline simdjson_result<T> get() & noexcept;
+  template<typename T> simdjson_inline simdjson_result<T> get() && noexcept;
+
+  template<typename T> simdjson_inline error_code get(T &out) & noexcept;
+  template<typename T> simdjson_inline error_code get(T &out) && noexcept;
 #if SIMDJSON_EXCEPTIONS
-  template <class T, typename std::enable_if<std::is_same<T, SIMDJSON_IMPLEMENTATION::ondemand::document_reference>::value == false>::type>
+  template <class T>
   explicit simdjson_inline operator T() noexcept(false);
   simdjson_inline operator SIMDJSON_IMPLEMENTATION::ondemand::array() & noexcept(false);
   simdjson_inline operator SIMDJSON_IMPLEMENTATION::ondemand::object() & noexcept(false);

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

@@ -152,7 +152,6 @@ simdjson_inline document_stream::iterator::iterator(document_stream* _stream, bo
 }
 
 simdjson_inline simdjson_result<ondemand::document_reference> document_stream::iterator::operator*() noexcept {
-  //if(stream->error) { return stream->error; }
   return simdjson_result<ondemand::document_reference>(stream->doc, stream->error);
 }
 

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

@@ -0,0 +1,281 @@
+/**
+ * This file is part of the builder API. It is temporarily in the ondemand directory
+ * but we will move it to a builder directory later.
+ */
+#include <type_traits>
+#ifndef SIMDJSON_GENERIC_BUILDER_INL_H
+
+#ifndef SIMDJSON_CONDITIONAL_INCLUDE
+#define SIMDJSON_GENERIC_BUILDER_INL_H
+#include "simdjson/generic/builder/json_string_builder.h"
+#endif // SIMDJSON_CONDITIONAL_INCLUDE
+
+namespace simdjson {
+namespace SIMDJSON_IMPLEMENTATION {
+namespace builder {
+
+simdjson_inline string_builder::string_builder(size_t initial_capacity) :
+  buffer(new (std::nothrow) char[initial_capacity]),
+  position(0), capacity(buffer.get() != nullptr ? initial_capacity : 0),
+  is_valid(buffer.get() != nullptr) {}
+
+simdjson_inline bool string_builder::capacity_check(size_t upcoming_bytes) {
+  // We use the convention that when is_valid is false, then the capacity and
+  // the position are 0.
+  // Most of the time, this function will return true.
+  if (simdjson_likely(upcoming_bytes <= capacity - position)) { return true; }
+  // check for overflow, most of the time there is no overflow
+  if (simdjson_likely(position + upcoming_bytes < position)) { return false; }
+  // We will rarely get here.
+  grow_buffer((std::max)(capacity * 2, position + upcoming_bytes));
+  // If the buffer allocation failed, we set is_valid to false.
+  return is_valid;
+}
+
+simdjson_inline void string_builder::grow_buffer(size_t desired_capacity) {
+  if (!is_valid) { return; }
+  std::unique_ptr<char[]> new_buffer(new (std::nothrow) char[desired_capacity]);
+  if (new_buffer.get() == nullptr) {
+    set_valid(false);
+    return;
+  }
+  std::memcpy(new_buffer.get(), buffer.get(), position);
+  buffer.swap(new_buffer);
+  capacity = desired_capacity;
+}
+
+simdjson_inline void string_builder::set_valid(bool valid) noexcept {
+  if(!valid) {
+    is_valid = false;
+    capacity = 0;
+    position = 0;
+    buffer.reset();
+  } else {
+    is_valid = true;
+  }
+}
+
+simdjson_inline size_t string_builder::size() const noexcept {
+  return position;
+}
+
+
+simdjson_inline void string_builder::append(char c) noexcept {
+    if(capacity_check(1)) {
+      buffer.get()[position++] = c;
+    }
+}
+
+
+simdjson_inline void string_builder::append_null() noexcept {
+  constexpr char null_literal[] = "null";
+  constexpr size_t null_len = sizeof(null_literal) - 1;
+  if(capacity_check(null_len)) {
+    std::memcpy(buffer.get() + position, null_literal, null_len);
+    position += null_len;
+  }
+}
+
+simdjson_inline void string_builder::clear()  noexcept {
+  position = 0;
+  // if it was invalid, we should try to repair it
+  if(!is_valid) {
+    capacity = 0;
+    buffer.reset();
+    is_valid = true;
+  }
+}
+
+namespace internal {
+
+// We could specialize further for 32-bit integers.
+int int_log2(uint32_t x) { return (63 - leading_zeroes(x | 1)); }
+
+int fast_digit_count_32(uint32_t x) {
+  static uint64_t table[] = {
+      4294967296,  8589934582,  8589934582,  8589934582,  12884901788,
+      12884901788, 12884901788, 17179868184, 17179868184, 17179868184,
+      21474826480, 21474826480, 21474826480, 21474826480, 25769703776,
+      25769703776, 25769703776, 30063771072, 30063771072, 30063771072,
+      34349738368, 34349738368, 34349738368, 34349738368, 38554705664,
+      38554705664, 38554705664, 41949672960, 41949672960, 41949672960,
+      42949672960, 42949672960};
+  return uint32_t((x + table[int_log2(x)]) >> 32);
+}
+
+int int_log2(uint64_t x) { return 63 - leading_zeroes(x | 1); }
+
+int digit_count_64(uint64_t x) {
+  static uint64_t table[] = {9,
+                             99,
+                             999,
+                             9999,
+                             99999,
+                             999999,
+                             9999999,
+                             99999999,
+                             999999999,
+                             9999999999,
+                             99999999999,
+                             999999999999,
+                             9999999999999,
+                             99999999999999,
+                             999999999999999ULL,
+                             9999999999999999ULL,
+                             99999999999999999ULL,
+                             999999999999999999ULL,
+                             9999999999999999999ULL};
+  int y = (19 * int_log2(x) >> 6);
+  y += x > table[y];
+  return y + 1;
+}
+
+template<typename number_type,
+         typename = typename std::enable_if<std::is_unsigned<number_type>::value>::type>
+simdjson_inline size_t digit_count(number_type v) noexcept {
+  static_assert(sizeof(number_type) == 8
+   || sizeof(number_type) == 4
+   || sizeof(number_type) == 2
+   || sizeof(number_type) == 1, "We only support 8-bit, 16-bit, 32-bit and 64-bit numbers");
+  if (sizeof(number_type) <= 4) {
+    return fast_digit_count_32(v);
+  } else {
+    return digit_count_64(v);
+  }
+}
+
+} // internal
+
+template<typename number_type, typename>
+simdjson_inline void string_builder::append(number_type v) noexcept {
+  static_assert(std::is_same<number_type, bool>::value
+    || std::is_integral<number_type>::value || std::is_floating_point<number_type>::value, "Unsupported number type");
+  // If C++17 is available, we can 'if constexpr' here.
+  if constexpr (std::is_same<number_type, bool>::value) {
+    if (v) {
+      constexpr char true_literal[] = "true";
+      constexpr size_t true_len = sizeof(true_literal) - 1;
+      if(capacity_check(true_len)) {
+        std::memcpy(buffer.get() + position, true_literal, true_len);
+        position += true_len;
+      }
+    } else {
+      constexpr char false_literal[] = "false";
+      constexpr size_t false_len = sizeof(false_literal) - 1;
+      if(capacity_check(false_len)) {
+        std::memcpy(buffer.get() + position, false_literal, false_len);
+        position += false_len;
+      }
+    }
+  } else if constexpr (std::is_unsigned<number_type>::value) {
+    constexpr size_t max_number_size = 20;
+    if(capacity_check(max_number_size)) {
+      using unsigned_type = typename std::make_unsigned<number_type>::type;
+      unsigned_type pv = static_cast<unsigned_type>(v);
+      size_t dc = internal::digit_count(pv);
+      char *write_pointer = buffer.get() + position + dc - 1;
+      // optimization opportunity: if v is large, we can do better.
+      while(pv >= 10) {
+        *write_pointer-- = char('0' + (pv % 10));
+        pv /= 10;
+      }
+      *write_pointer = char('0' + pv);
+      position += dc;
+    }
+  } else if constexpr (std::is_integral<number_type>::value) {
+    constexpr size_t max_number_size = 20;
+    if(capacity_check(max_number_size)) {
+      using unsigned_type = typename std::make_unsigned<number_type>::type;
+      bool negative = v < 0;
+      unsigned_type pv = static_cast<unsigned_type>(negative ? -v : v);
+      size_t dc = internal::digit_count(pv);
+      if(negative) {
+        buffer.get()[position++] = '-';
+      }
+      char *write_pointer = buffer.get() + position + dc - 1;
+      // optimization opportunity: if v is large, we can do better.
+      while(pv >= 10) {
+        *write_pointer-- = char('0' + (pv % 10));
+        pv /= 10;
+      }
+      *write_pointer = char('0' + pv);
+      position += dc;
+    }
+  } else if constexpr (std::is_floating_point<number_type>::value) {
+    constexpr size_t max_number_size = 24;
+    if(capacity_check(max_number_size)) {
+      // We could specialize for float.
+      char *end = simdjson::internal::to_chars(buffer.get() + position, nullptr, double(v));
+      position = end - buffer.get();
+    }
+  }
+}
+
+simdjson_inline void string_builder::escape_and_append(std::string_view input)  noexcept {
+  // escaping might turn a control character into \x00xx so 6 characters.
+  if(capacity_check(6 * input.size())) {
+    position += simdjson::write_string_escaped(input, buffer.get() + position);
+  }
+}
+
+simdjson_inline void string_builder::escape_and_append_with_quotes(std::string_view input)  noexcept {
+  // escaping might turn a control character into \x00xx so 6 characters.
+  if(capacity_check(2 + 6 * input.size())) {
+    buffer.get()[position++] = '"';
+    position += simdjson::write_string_escaped(input, buffer.get() + position);
+    buffer.get()[position++] = '"';
+  }
+}
+
+simdjson_inline void string_builder::append_raw(const char *c)  noexcept {
+  if(capacity_check(1)) {
+    buffer.get()[position++] = *c;
+  }
+}
+
+simdjson_inline void string_builder::append_raw(std::string_view input)  noexcept {
+  if(capacity_check(input.size())) {
+    std::memcpy(buffer.get() + position, input.data(), input.size());
+    position += input.size();
+  }
+}
+
+simdjson_inline void string_builder::append_raw(const char *str, size_t len)  noexcept {
+  if(capacity_check(len)) {
+    std::memcpy(buffer.get() + position, str, len);
+    position += len;
+  }
+}
+
+#if SIMDJSON_EXCEPTIONS
+simdjson_inline string_builder::operator std::string() const noexcept(false) {
+  return std::string(std::string_view());
+}
+
+simdjson_inline string_builder::operator std::string_view() const noexcept(false) {
+  return view();
+}
+#endif
+
+simdjson_inline simdjson_result<std::string_view> string_builder::view() const noexcept {
+  if (!is_valid) { return simdjson::OUT_OF_CAPACITY; }
+  return std::string_view(buffer.get(), position);
+}
+
+simdjson_inline simdjson_result<const char *> string_builder::c_str() noexcept {
+  if(capacity_check(1)) {
+    buffer.get()[position] = '\0';
+    return buffer.get();
+  }
+  return simdjson::OUT_OF_CAPACITY;
+}
+
+simdjson_inline bool string_builder::validate_unicode() const noexcept {
+  return simdjson::validate_utf8(buffer.get(), position);
+}
+
+} // namespace builder
+} // namespace SIMDJSON_IMPLEMENTATION
+} // namespace simdjson
+
+#endif // SIMDJSON_GENERIC_BUILDER_INL_H

include/simdjson/generic/ondemand/json_string_builder.h

@@ -0,0 +1,167 @@
+/**
+ * This file is part of the builder API. It is temporarily in the ondemand directory
+ * but we will move it to a builder directory later.
+ */
+#ifndef SIMDJSON_GENERIC_BUILDER_H
+
+#ifndef SIMDJSON_CONDITIONAL_INCLUDE
+#define SIMDJSON_GENERIC_BUILDER_H
+#include "simdjson/generic/implementation_simdjson_result_base.h"
+#endif // SIMDJSON_CONDITIONAL_INCLUDE
+
+namespace simdjson {
+namespace SIMDJSON_IMPLEMENTATION {
+namespace builder {
+
+/**
+ * A builder for JSON strings representing documents. This is a low-level
+ * builder that is not meant to be used directly by end-users. Though it
+ * supports atomic types (Booleans, strings), it does not support composed
+ * types (arrays and objects).
+ *
+ * Ultimately, this class should support kernel-specific optimizations. E.g.,
+ * it may make use of SIMD instructions to escape strings faster.
+ */
+class string_builder {
+public:
+  simdjson_inline string_builder(size_t initial_capacity = 1024);
+
+  /**
+   * Append number (includes Booleans). Booleans are mapped to the strings
+   * false and true. Numbers are converted to strings abiding by the JSON standard.
+   * Floating-point numbers are converted to the shortest string that 'correctly'
+   * represents the number.
+   */
+  template<typename number_type,
+         typename = typename std::enable_if<std::is_arithmetic<number_type>::value>::type>
+  simdjson_inline void append(number_type v) noexcept;
+
+  /**
+   * Append character c.
+   */
+  simdjson_inline void append(char c)  noexcept;
+
+  /**
+   * Append the string 'null'.
+   */
+  simdjson_inline void append_null()  noexcept;
+
+  /**
+   * Clear the content.
+   */
+  simdjson_inline void clear()  noexcept;
+
+  /**
+   * Append the std::string_view, after escaping it.
+   * There is no UTF-8 validation.
+   */
+  simdjson_inline void escape_and_append(std::string_view input)  noexcept;
+
+  /**
+   * Append the std::string_view surrounded by double quotes, after escaping it.
+   * There is no UTF-8 validation.
+   */
+  simdjson_inline void escape_and_append_with_quotes(std::string_view input)  noexcept;
+
+  /**
+   * Append the C string directly, without escaping.
+   * There is no UTF-8 validation.
+   */
+  simdjson_inline void append_raw(const char *c)  noexcept;
+
+  /**
+   * Append the std::string_view directly, without escaping.
+   * There is no UTF-8 validation.
+   */
+  simdjson_inline void append_raw(std::string_view input)  noexcept;
+
+  /**
+   * Append len characters from str.
+   * There is no UTF-8 validation.
+   */
+  simdjson_inline void append_raw(const char *str, size_t len) noexcept;
+#if SIMDJSON_EXCEPTIONS
+  /**
+   * Creates an std::string from the written JSON buffer.
+   * Throws if memory allocation failed
+   *
+   * The result may not be valid UTF-8 if some of your content was not valid UTF-8.
+   * Use validate_unicode() to check the content if needed.
+   */
+  simdjson_inline operator std::string() const noexcept(false);
+
+  /**
+   * Creates an std::string_view from the written JSON buffer.
+   * Throws if memory allocation failed.
+   *
+   * The result may not be valid UTF-8 if some of your content was not valid UTF-8.
+   * Use validate_unicode() to check the content if needed.
+   */
+  simdjson_inline operator std::string_view() const noexcept(false);
+#endif
+
+  /**
+   * Returns a view on the written JSON buffer. Returns an error
+   * if memory allocation failed.
+   *
+   * The result may not be valid UTF-8 if some of your content was not valid UTF-8.
+   * Use validate_unicode() to check the content.
+   */
+  simdjson_inline simdjson_result<std::string_view> view() const noexcept;
+
+  /**
+   * Appends the null character to the buffer and returns
+   * a pointer to the beginning of the written JSON buffer.
+   * Returns an error if memory allocation failed.
+   * The result is null-terminated.
+   *
+   * The result may not be valid UTF-8 if some of your content was not valid UTF-8.
+   * Use validate_unicode() to check the content.
+   */
+  simdjson_inline simdjson_result<const char *> c_str() noexcept;
+
+  /**
+   * Return true if the content is valid UTF-8.
+   */
+  simdjson_inline bool validate_unicode() const noexcept;
+
+  /**
+   * Returns the current size of the written JSON buffer.
+   * If an error occurred, returns 0.
+   */
+  simdjson_inline size_t size() const noexcept;
+
+private:
+  /**
+   * Returns true if we can write at least upcoming_bytes bytes.
+   * The underlying buffer is reallocated if needed. It is designed
+   * to be called before writing to the buffer. It should be fast.
+   */
+  simdjson_inline bool capacity_check(size_t upcoming_bytes);
+
+  /**
+   * Grow the buffer to at least desired_capacity bytes.
+   * If the allocation fails, is_valid is set to false. We expect
+   * that this function would not be repeatedly called.
+   */
+  simdjson_inline void grow_buffer(size_t desired_capacity);
+
+  /**
+   * We use this helper function to make sure that is_valid is kept consistent.
+   */
+  simdjson_inline void set_valid(bool valid) noexcept;
+
+
+  std::unique_ptr<char[]> buffer{};
+  size_t position{0};
+  size_t capacity{0};
+  bool is_valid{true};
+};
+
+
+
+}
+}
+} // namespace simdjson
+
+#endif // SIMDJSON_GENERIC_BUILDER_H

include/simdjson/generic/ondemand/std_deserialize.h

@@ -0,0 +1,166 @@
+#if SIMDJSON_SUPPORTS_DESERIALIZATION
+
+#ifndef SIMDJSON_ONDEMAND_DESERIALIZE_H
+#ifndef SIMDJSON_CONDITIONAL_INCLUDE
+#define SIMDJSON_ONDEMAND_DESERIALIZE_H
+#include "simdjson/generic/ondemand/array.h"
+#include "simdjson/generic/ondemand/base.h"
+#endif // SIMDJSON_CONDITIONAL_INCLUDE
+
+#include <concepts>
+#include <limits>
+
+namespace simdjson {
+template <typename T>
+constexpr bool require_custom_serialization = false;
+
+//////////////////////////////
+// Number deserialization
+//////////////////////////////
+
+template <std::unsigned_integral T>
+  requires(!require_custom_serialization<T>)
+error_code tag_invoke(deserialize_tag, auto &val, T &out) noexcept {
+  using limits = std::numeric_limits<T>;
+
+  uint64_t x;
+  SIMDJSON_TRY(val.get_uint64().get(x));
+  if (x > (limits::max)()) {
+    return NUMBER_OUT_OF_RANGE;
+  }
+  out = static_cast<T>(x);
+  return SUCCESS;
+}
+
+template <std::floating_point T>
+  requires(!require_custom_serialization<T>)
+error_code tag_invoke(deserialize_tag, auto &val, T &out) noexcept {
+  double x;
+  SIMDJSON_TRY(val.get_double().get(x));
+  out = static_cast<T>(x);
+  return SUCCESS;
+}
+
+template <std::signed_integral T>
+  requires(!require_custom_serialization<T>)
+error_code tag_invoke(deserialize_tag, auto &val, T &out) noexcept {
+  using limits = std::numeric_limits<T>;
+
+  int64_t x;
+  SIMDJSON_TRY(val.get_int64().get(x));
+  if (x > (limits::max)() || x < (limits::min)()) {
+    return NUMBER_OUT_OF_RANGE;
+  }
+  out = static_cast<T>(x);
+  return SUCCESS;
+}
+
+/**
+ * STL containers have several constructors including one that takes a single
+ * size argument. Thus, some compilers (Visual Studio) will not be able to
+ * disambiguate between the size and container constructor. Users should
+ * explicitly specify the type of the container as needed: e.g.,
+ * doc.get<std::vector<int>>().
+ */
+template <concepts::appendable_containers T, typename ValT>
+  requires(!require_custom_serialization<T>)
+error_code tag_invoke(deserialize_tag, ValT &val, T &out) noexcept(false) {
+  using value_type = typename std::remove_cvref_t<T>::value_type;
+  static_assert(
+      deserializable<value_type, ValT>,
+      "The specified type inside the container must itself be deserializable");
+  static_assert(
+      std::is_default_constructible_v<value_type>,
+      "The specified type inside the container must default constructible.");
+
+  SIMDJSON_IMPLEMENTATION::ondemand::array arr;
+  SIMDJSON_TRY(val.get_array().get(arr));
+  for (auto v : arr) {
+    if constexpr (concepts::returns_reference<T>) {
+      if (auto const err = v.get<value_type>().get(concepts::emplace_one(out));
+          err) {
+        // If an error occurs, the empty element that we just inserted gets
+        // removed. We're not using a temp variable because if T is a heavy
+        // type, we want the valid path to be the fast path and the slow path be
+        // the path that has errors in it.
+        if constexpr (requires { out.pop_back(); }) {
+          static_cast<void>(out.pop_back());
+        }
+        return err;
+      }
+    } else {
+      value_type temp;
+      if (auto const err = v.get<value_type>().get(temp); err) {
+        return err;
+      }
+      concepts::emplace_one(out, std::move(temp));
+    }
+  }
+  return SUCCESS;
+}
+
+
+
+/**
+ * This CPO (Customization Point Object) will help deserialize into
+ * smart pointers.
+ *
+ * If constructing T is nothrow, this conversion should be nothrow as well since
+ * we return MEMALLOC if we're not able to allocate memory instead of throwing
+ * the error message.
+ *
+ * @tparam T The type inside the smart pointer
+ * @tparam ValT document/value type
+ * @param val document/value
+ * @param out a reference to the smart pointer
+ * @return status of the conversion
+ */
+template <concepts::smart_pointer T, typename ValT>
+  requires(!require_custom_serialization<T>)
+error_code tag_invoke(deserialize_tag, ValT &val, T &out) noexcept(nothrow_deserializable<typename std::remove_cvref_t<T>::element_type, ValT>) {
+  using element_type = typename std::remove_cvref_t<T>::element_type;
+
+  // For better error messages, don't use these as constraints on
+  // the tag_invoke CPO.
+  static_assert(
+      deserializable<element_type, ValT>,
+      "The specified type inside the unique_ptr must itself be deserializable");
+  static_assert(
+      std::is_default_constructible_v<element_type>,
+      "The specified type inside the unique_ptr must default constructible.");
+
+  auto ptr = new (std::nothrow) element_type();
+  if (ptr == nullptr) {
+    return MEMALLOC;
+  }
+  SIMDJSON_TRY(val.template get<element_type>(*ptr));
+  out.reset(ptr);
+  return SUCCESS;
+}
+
+/**
+ * This CPO (Customization Point Object) will help deserialize into optional types.
+ */
+template <concepts::optional_type T, typename ValT>
+  requires(!require_custom_serialization<T>)
+error_code tag_invoke(deserialize_tag, ValT &val, T &out) noexcept(nothrow_deserializable<typename std::remove_cvref_t<T>::value_type, ValT>) {
+  using value_type = typename std::remove_cvref_t<T>::value_type;
+
+  static_assert(
+      deserializable<value_type, ValT>,
+      "The specified type inside the unique_ptr must itself be deserializable");
+  static_assert(
+      std::is_default_constructible_v<value_type>,
+      "The specified type inside the unique_ptr must default constructible.");
+
+  if (!out) {
+    out.emplace();
+  }
+  SIMDJSON_TRY(val.template get<value_type>(out.value()));
+  return SUCCESS;
+}
+
+} // namespace simdjson
+
+#endif // SIMDJSON_ONDEMAND_DESERIALIZE_H
+#endif // SIMDJSON_SUPPORTS_DESERIALIZATION

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

@@ -78,6 +78,7 @@ simdjson_inline simdjson_result<bool> value::get_bool() noexcept {
 simdjson_inline simdjson_result<bool> value::is_null() noexcept {
   return iter.is_null();
 }
+
 template<> simdjson_inline simdjson_result<array> value::get() noexcept { return get_array(); }
 template<> simdjson_inline simdjson_result<object> value::get() noexcept { return get_object(); }
 template<> simdjson_inline simdjson_result<raw_json_string> value::get() noexcept { return get_raw_json_string(); }
@@ -88,9 +89,16 @@ template<> simdjson_inline simdjson_result<uint64_t> value::get() noexcept { ret
 template<> simdjson_inline simdjson_result<int64_t> value::get() noexcept { return get_int64(); }
 template<> simdjson_inline simdjson_result<bool> value::get() noexcept { return get_bool(); }
 
-template<typename T> simdjson_inline error_code value::get(T &out) noexcept {
+
-  return get<T>().get(out);
+template<> simdjson_inline error_code value::get(array& out) noexcept { return get_array().get(out); }
-}
+template<> simdjson_inline error_code value::get(object& out) noexcept { return get_object().get(out); }
+template<> simdjson_inline error_code value::get(raw_json_string& out) noexcept { return get_raw_json_string().get(out); }
+template<> simdjson_inline error_code value::get(std::string_view& out) noexcept { return get_string(false).get(out); }
+template<> simdjson_inline error_code value::get(number& out) noexcept { return get_number().get(out); }
+template<> simdjson_inline error_code value::get(double& out) noexcept { return get_double().get(out); }
+template<> simdjson_inline error_code value::get(uint64_t& out) noexcept { return get_uint64().get(out); }
+template<> simdjson_inline error_code value::get(int64_t& out) noexcept { return get_int64().get(out); }
+template<> simdjson_inline error_code value::get(bool& out) noexcept { return get_bool().get(out); }
 
 #if SIMDJSON_EXCEPTIONS
 template <class T>
@@ -414,6 +422,12 @@ simdjson_inline simdjson_result<bool> simdjson_result<SIMDJSON_IMPLEMENTATION::o
   return first.is_null();
 }
 
+template<> simdjson_inline error_code simdjson_result<SIMDJSON_IMPLEMENTATION::ondemand::value>::get<SIMDJSON_IMPLEMENTATION::ondemand::value>(SIMDJSON_IMPLEMENTATION::ondemand::value &out) noexcept {
+  if (error()) { return error(); }
+  out = first;
+  return SUCCESS;
+}
+
 template<typename T> simdjson_inline simdjson_result<T> simdjson_result<SIMDJSON_IMPLEMENTATION::ondemand::value>::get() noexcept {
   if (error()) { return error(); }
   return first.get<T>();
@@ -427,11 +441,6 @@ template<> simdjson_inline simdjson_result<SIMDJSON_IMPLEMENTATION::ondemand::va
   if (error()) { return error(); }
   return std::move(first);
 }
-template<> simdjson_inline error_code simdjson_result<SIMDJSON_IMPLEMENTATION::ondemand::value>::get<SIMDJSON_IMPLEMENTATION::ondemand::value>(SIMDJSON_IMPLEMENTATION::ondemand::value &out) noexcept {
-  if (error()) { return error(); }
-  out = first;
-  return SUCCESS;
-}
 
 simdjson_inline simdjson_result<SIMDJSON_IMPLEMENTATION::ondemand::json_type> simdjson_result<SIMDJSON_IMPLEMENTATION::ondemand::value>::type() noexcept {
   if (error()) { return error(); }
@@ -465,7 +474,7 @@ simdjson_inline simdjson_result<SIMDJSON_IMPLEMENTATION::ondemand::number> simdj
 template <class T>
 simdjson_inline simdjson_result<SIMDJSON_IMPLEMENTATION::ondemand::value>::operator T() noexcept(false) {
   if (error()) { throw simdjson_error(error()); }
-  return static_cast<T>(first);
+  return first.get<T>();
 }
 simdjson_inline simdjson_result<SIMDJSON_IMPLEMENTATION::ondemand::value>::operator SIMDJSON_IMPLEMENTATION::ondemand::array() noexcept(false) {
   if (error()) { throw simdjson_error(error()); }

include/simdjson/generic/ondemand/value.h

@@ -5,12 +5,15 @@
 #include "simdjson/generic/ondemand/base.h"
 #include "simdjson/generic/implementation_simdjson_result_base.h"
 #include "simdjson/generic/ondemand/value_iterator.h"
+#include "simdjson/generic/ondemand/deserialize.h"
 #endif // SIMDJSON_CONDITIONAL_INCLUDE
 
+#include <type_traits>
+
 namespace simdjson {
+
 namespace SIMDJSON_IMPLEMENTATION {
 namespace ondemand {
-
 /**
  * An ephemeral JSON value returned during iteration. It is only valid for as long as you do
  * not access more data in the JSON document.
@@ -35,16 +38,21 @@ public:
    * @returns A value of the given type, parsed from the JSON.
    * @returns INCORRECT_TYPE If the JSON value is not the given type.
    */
-  template<typename T> simdjson_inline simdjson_result<T> get() noexcept {
+  template <typename T>
-    // Unless the simdjson library or the user provides an inline implementation, calling this method should
+  simdjson_inline simdjson_result<T> get()
-    // immediately fail.
+#if SIMDJSON_SUPPORTS_DESERIALIZATION
-    static_assert(!sizeof(T), "The get method with given type is not implemented by the simdjson library. "
+    noexcept(custom_deserializable<T, value> ? nothrow_custom_deserializable<T, value> : true)
-      "The supported types are ondemand::object, ondemand::array, raw_json_string, std::string_view, uint64_t, "
+#else
-      "int64_t, double, and bool. We recommend you use get_double(), get_bool(), get_uint64(), get_int64(), "
+    noexcept
-      " get_object(), get_array(), get_raw_json_string(), or get_string() instead of the get template."
+#endif
-      " You may also add support for custom types, see our documentation.");
+  {
+    static_assert(std::is_default_constructible<T>::value, "The specified type is not default constructible.");
+    T out{};
+    SIMDJSON_TRY(get<T>(out));
+    return out;
   }
 
+
   /**
    * Get this value as the given type.
    *
@@ -54,7 +62,32 @@ public:
    * @returns INCORRECT_TYPE If the JSON value is not an object.
    * @returns SUCCESS If the parse succeeded and the out parameter was set to the value.
    */
-  template<typename T> simdjson_inline error_code get(T &out) noexcept;
+  template <typename T>
+  simdjson_inline error_code get(T &out)
+#if SIMDJSON_SUPPORTS_DESERIALIZATION
+    noexcept(custom_deserializable<T, value> ? nothrow_custom_deserializable<T, value> : true)
+#else
+    noexcept
+#endif
+ {
+#if SIMDJSON_SUPPORTS_DESERIALIZATION
+    if constexpr (custom_deserializable<T, value>) {
+      return deserialize(*this, out);
+    } else {
+#endif // SIMDJSON_SUPPORTS_DESERIALIZATION
+      // Unless the simdjson library or the user provides an inline implementation, calling this method should
+      // immediately fail.
+      static_assert(!sizeof(T), "The get method with given type is not implemented by the simdjson library. "
+        "The supported types are ondemand::object, ondemand::array, raw_json_string, std::string_view, uint64_t, "
+        "int64_t, double, and bool. We recommend you use get_double(), get_bool(), get_uint64(), get_int64(), "
+        " get_object(), get_array(), get_raw_json_string(), or get_string() instead of the get template."
+        " You may also add support for custom types, see our documentation.");
+      static_cast<void>(out); // to get rid of unused errors
+      return UNINITIALIZED;
+#if SIMDJSON_SUPPORTS_DESERIALIZATION
+    }
+#endif
+  }
 
   /**
    * Cast this JSON value to an array.

include/simdjson/haswell/implementation.h

@@ -28,6 +28,7 @@ public:
   ) const noexcept final;
   simdjson_warn_unused error_code minify(const uint8_t *buf, size_t len, uint8_t *dst, size_t &dst_len) const noexcept final;
   simdjson_warn_unused bool validate_utf8(const char *buf, size_t len) const noexcept final;
+  simdjson_warn_unused size_t write_string_escaped(const std::string_view input, char *out) const noexcept final;
 };
 
 } // namespace haswell

include/simdjson/haswell/stringparsing_defs.h

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

include/simdjson/icelake/implementation.h

@@ -28,6 +28,7 @@ public:
   ) const noexcept final;
   simdjson_warn_unused error_code minify(const uint8_t *buf, size_t len, uint8_t *dst, size_t &dst_len) const noexcept final;
   simdjson_warn_unused bool validate_utf8(const char *buf, size_t len) const noexcept final;
+  simdjson_warn_unused size_t write_string_escaped(const std::string_view input, char *out) const noexcept final;
 };
 
 } // namespace icelake

include/simdjson/icelake/simd.h

@@ -77,7 +77,6 @@ namespace simd {
     friend simdjson_really_inline uint64_t operator==(const simd8<T> lhs, const simd8<T> rhs) {
       return _mm512_cmpeq_epi8_mask(lhs, rhs);
     }
-
     static const int SIZE = sizeof(base<T>::value);
 
     template<int N=1>

include/simdjson/icelake/stringparsing_defs.h

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

include/simdjson/implementation.h

@@ -26,6 +26,15 @@ simdjson_inline simdjson_warn_unused bool validate_utf8(const std::string_view s
   return validate_utf8(sv.data(), sv.size());
 }
 
+/**
+ * Write the string to the output buffer while escaping double-quote, backlash and ascii control characters.
+ *
+ * @param input the string_view to escape
+ * @param out output buffer (for escaped string): to be safe, it should have 6 * input.size() allocated bytes.
+ * @return number of bytes written
+ */
+simdjson_warn_unused size_t write_string_escaped(const std::string_view input, char *out) noexcept;
+
 /**
  * Validate the UTF-8 string.
  *
@@ -127,6 +136,14 @@ public:
    */
   simdjson_warn_unused virtual bool validate_utf8(const char *buf, size_t len) const noexcept = 0;
 
+  /**
+   * Write the string to the output buffer while escaping double-quote, backlash and ascii control characters.
+   *
+   * @param input the string_view to escape
+   * @param out output buffer (for escaped string): to be safe, it should have 6 * input.size() allocated bytes.
+   * @return number of bytes written
+   */
+  simdjson_warn_unused virtual size_t write_string_escaped(const std::string_view input, char *out) const noexcept = 0;
 protected:
   /** @private Construct an implementation with the given name and description. For subclasses. */
   simdjson_inline implementation(

include/simdjson/lasx/implementation.h

@@ -23,6 +23,7 @@ public:
   ) const noexcept final;
   simdjson_warn_unused error_code minify(const uint8_t *buf, size_t len, uint8_t *dst, size_t &dst_len) const noexcept final;
   simdjson_warn_unused bool validate_utf8(const char *buf, size_t len) const noexcept final;
+  simdjson_warn_unused size_t write_string_escaped(const std::string_view input, char *out) const noexcept final;
 };
 
 } // namespace lasx

include/simdjson/lasx/stringparsing_defs.h

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

include/simdjson/lsx/implementation.h

@@ -23,6 +23,7 @@ public:
   ) const noexcept final;
   simdjson_warn_unused error_code minify(const uint8_t *buf, size_t len, uint8_t *dst, size_t &dst_len) const noexcept final;
   simdjson_warn_unused bool validate_utf8(const char *buf, size_t len) const noexcept final;
+  simdjson_warn_unused size_t write_string_escaped(const std::string_view input, char *out) const noexcept final;
 };
 
 } // namespace lsx

include/simdjson/lsx/stringparsing_defs.h

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

include/simdjson/ondemand.h

@@ -8,6 +8,10 @@ namespace simdjson {
    * @copydoc simdjson::builtin::ondemand
    */
   namespace ondemand = builtin::ondemand;
+  /**
+   * @copydoc simdjson::builtin::builder
+   */
+  namespace builder = builtin::builder;
 } // namespace simdjson
 
 #endif // SIMDJSON_ONDEMAND_H

include/simdjson/ppc64/implementation.h

@@ -32,6 +32,7 @@ public:
                                          size_t &dst_len) const noexcept final;
   simdjson_warn_unused bool validate_utf8(const char *buf,
                                           size_t len) const noexcept final;
+  simdjson_warn_unused size_t write_string_escaped(const std::string_view input, char *out) const noexcept final;
 };
 
 } // namespace ppc64

include/simdjson/ppc64/stringparsing_defs.h

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

include/simdjson/westmere/implementation.h

@@ -24,6 +24,7 @@ public:
   ) const noexcept final;
   simdjson_warn_unused error_code minify(const uint8_t *buf, size_t len, uint8_t *dst, size_t &dst_len) const noexcept final;
   simdjson_warn_unused bool validate_utf8(const char *buf, size_t len) const noexcept final;
+  simdjson_warn_unused size_t write_string_escaped(const std::string_view input, char *out) const noexcept final;
 };
 
 } // namespace westmere

include/simdjson/westmere/stringparsing_defs.h

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

singleheader/amalgamate.py

@@ -10,12 +10,41 @@ import os
 import re
 import shutil
 import datetime
+import json
 from typing import Dict, List, Optional, Set, TextIO, Union, cast
 
+# Check for Python 3, this does not actually work.
 if sys.version_info < (3, 0):
     sys.stdout.write("Sorry, requires Python 3.x or better\n")
     sys.exit(1)
 
+rules = """
+
+We refer your to the HACKING.md file for more information on how the project is organized.
+
+To help understand the error, here are the rules for including files in simdjson:
+
+All implementation-specific files, including arm64.h, arm64/implementation.h and
+arm64/ondemand.h, must be within SIMDJSON_CONDITIONAL_INCLUDE blocks.
+
+Top-level headers must not be included in any SIMDJSON_CONDITIONAL_INCLUDE block.
+
+Generic files must be included only in amalgamator files (arm64.h,
+arm64/implementation.h, arm64/ondemand.h, generic/amalgamated.h).
+
+We fail if an implementation-specific file is included more than once in the same block.
+We fail if a generic file is included more than once per implementation in the same block.
+
+
+Tip: generally, "file" will search the including file's source directory first, then
+the search paths while <file> does it the other way around.
+We prefer to use <> in simdjson headers to avoid accidentally including a file from the
+wrong directory.
+
+The amalgamate.py script checks that all files are included.
+
+"""
+
 SCRIPTPATH = os.path.dirname(os.path.abspath(sys.argv[0]))
 PROJECTPATH = os.path.dirname(SCRIPTPATH)
 print(f"SCRIPTPATH={SCRIPTPATH} PROJECTPATH={PROJECTPATH}")
@@ -62,6 +91,22 @@ class SimdjsonFile:
     def __str__(self):
         return self.include_path
 
+    def dump(self):
+        return {
+            'root': self.root,
+            'include_path': self.include_path,
+            'includes': [include.include_path for include in self.includes],
+            'included_from': [included_from.include_path for included_from in self.included_from],
+            'editor_only_includes': [editor_only_include.include_path for editor_only_include in self.editor_only_includes],
+            'editor_only_included_from': [editor_only_included_from.include_path for editor_only_included_from in self.editor_only_included_from],
+            'processed': self.processed,
+            'dependency_file': self.dependency_file.include_path if self.dependency_file else None,
+            'is_amalgamator': self.is_amalgamator,
+            'implementation': self.implementation,
+        }
+    def json(self):
+        return json.dumps(self.dump(), indent=4, sort_keys=True, ensure_ascii=False)
+
     def __repr__(self):
         return self.include_path
 
@@ -162,20 +207,21 @@ class SimdjsonFile:
 
     def add_include(self, include: 'SimdjsonFile'):
         if self.is_conditional_include:
-            assert include.is_conditional_include, f"{self} cannot include {include} without #ifndef SIMDJSON_CONDITIONAL_INCLUDE."
+            # If I have a dependency file, I can only include something that has a dependency file.
+            assert include.is_conditional_include, f"{self} cannot include {include} without #ifndef SIMDJSON_CONDITIONAL_INCLUDE. {rules}"
             # TODO make sure we only include amalgamated files that are guaranteed to be included with us (or before us)
             # if include.amalgamator_file:
             #     assert include.amalgamator_file == self, f"{self} cannot include {include}: it should be included from {include.amalgamator_file} instead."
         else:
-            assert include.is_amalgamator or not include.is_conditional_include, f"{self} cannot include {include} because it is an amalgamated file."
+            assert include.is_amalgamator or not include.is_conditional_include, f"{self} cannot include {include} because it is an amalgamated file. {rules}"
 
         self.includes.append(include)
         include.included_from.add(self)
 
     def add_editor_only_include(self, include: 'SimdjsonFile'):
-        assert self.is_conditional_include, f"Cannot use #ifndef SIMDJSON_CONDITIONAL_INCLUDE in {self} because it is not an amalgamated file."
+        assert self.is_conditional_include, f"Cannot use #ifndef SIMDJSON_CONDITIONAL_INCLUDE in {self} because it is not an amalgamated file. {rules}"
         if not include.is_conditional_include:
-            assert self.dependency_file, f"{self} cannot include {include} without #ifndef SIMDJSON_CONDITIONAL_INCLUDE."
+            assert self.dependency_file, f"{self} cannot include {include} without #ifndef SIMDJSON_CONDITIONAL_INCLUDE. {rules}"
         # TODO make sure we only include amalgamated files that are guaranteed to be included with us (or before us)
         # elif include.amalgamator_file:
         #     assert self.is_amalgamated_before(self.amalgamator_file), f"{self} cannot include {include}: it should be included from {include.amalgamator_file} instead."
@@ -190,11 +236,11 @@ class SimdjsonFile:
                 if file.dependency_file == self:
                     for editor_only_include in file.editor_only_includes:
                         if not editor_only_include.is_conditional_include:
-                            assert editor_only_include in self.includes, f"{file} includes {editor_only_include}, but it is not included from {self}. It must be added to {self}."
+                            assert editor_only_include in self.includes, f"{file} includes {editor_only_include}, but it is not included from {self}. It must be added to {self}. {rules}"
                             if editor_only_include in extra_include_set:
                                 extra_include_set.remove(editor_only_include)
 
-            assert len(extra_include_set) == 0, f"{self} unnecessarily includes {extra_include_set}. They are not included in the corresponding amalgamated files."
+            assert len(extra_include_set) == 0, f"{self} unnecessarily includes {extra_include_set}. They are not included in the corresponding amalgamated files. {rules}"
 
 class SimdjsonRepository:
     def __init__(self, project_path: str, relative_roots: List[RelativeRoot]):
@@ -320,6 +366,7 @@ class Amalgamator:
 
         assert not self.editor_only_region
         with open(file.absolute_path, 'r') as fid2:
+            print(f"including: {file}")
             for line in fid2:
                 line = line.rstrip('\n')
 
@@ -329,9 +376,9 @@ class Amalgamator:
 
                 # Ignore lines inside #ifndef SIMDJSON_CONDITIONAL_INCLUDE
                 if re.search(r'^#ifndef\s+SIMDJSON_CONDITIONAL_INCLUDE\s*$', line):
-                    assert file.is_conditional_include, f"{file} uses #ifndef SIMDJSON_CONDITIONAL_INCLUDE but is not an amalgamated file!"
+                    assert file.is_conditional_include, f"{file} uses #ifndef SIMDJSON_CONDITIONAL_INCLUDE but is not an amalgamated file! {rules}"
-                    assert self.in_conditional_include_block, f"{file} uses #ifndef SIMDJSON_CONDITIONAL_INCLUDE without a prior #define SIMDJSON_CONDITIONAL_INCLUDE: {self.include_stack}"
+                    assert self.in_conditional_include_block, f"{file} uses #ifndef SIMDJSON_CONDITIONAL_INCLUDE without a prior #define SIMDJSON_CONDITIONAL_INCLUDE: {self.include_stack} {rules}"
-                    assert not self.editor_only_region, f"{file} uses #ifndef SIMDJSON_CONDITIONAL_INCLUDE twice in a row"
+                    assert not self.editor_only_region, f"{file} uses #ifndef SIMDJSON_CONDITIONAL_INCLUDE twice in a row {rules}"
                     self.editor_only_region = True
 
                 # Handle ignored lines (and ending ignore blocks)
@@ -349,7 +396,7 @@ class Amalgamator:
                         self.editor_only_region = False
                     continue
 
-                assert not end_ignore, f"{file} has #endif // SIMDJSON_CONDITIONAL_INCLUDE without #ifndef SIMDJSON_CONDITIONAL_INCLUDE"
+                assert not end_ignore, f"{file} has #endif // SIMDJSON_CONDITIONAL_INCLUDE without #ifndef SIMDJSON_CONDITIONAL_INCLUDE {rules}"
 
                 # Handle #include lines
                 included = re.search(r'^#include\s+["<]([^">]*)[">]', line)
@@ -376,26 +423,26 @@ class Amalgamator:
                     self.implementation = None
                 elif re.search(r'\bSIMDJSON_IMPLEMENTATION\b', line) and file.include_path != IMPLEMENTATION_DETECTION_H:
                     # copy the line, with SIMDJSON_IMPLEMENTATION replace to what it is currently defined to
-                    assert self.implementation, f"Use of SIMDJSON_IMPLEMENTATION while not defined in {file}: {line}"
+                    assert self.implementation, f"Use of SIMDJSON_IMPLEMENTATION while not defined in {file}: {line}\n{rules}"
                     line = re.sub(r'\bSIMDJSON_IMPLEMENTATION\b',self.implementation,line)
 
                 # Handle defining and undefining SIMDJSON_CONDITIONAL_INCLUDE
                 defined = re.search(r'^#define\s+SIMDJSON_CONDITIONAL_INCLUDE\s*$', line)
                 if defined:
-                    assert not file.is_conditional_include, "SIMDJSON_CONDITIONAL_INCLUDE defined in amalgamated file {file}! Not allowed."
+                    assert not file.is_conditional_include, "SIMDJSON_CONDITIONAL_INCLUDE defined in amalgamated file {file}! Not allowed. {rules}"
-                    assert not self.in_conditional_include_block, f"{file} redefines SIMDJSON_CONDITIONAL_INCLUDE"
+                    assert not self.in_conditional_include_block, f"{file} redefines SIMDJSON_CONDITIONAL_INCLUDE {rules}"
                     self.in_conditional_include_block = True
                     self.found_includes_per_conditional_block.clear()
                     self.write(f'/* defining SIMDJSON_CONDITIONAL_INCLUDE */')
                 elif re.search(r'^#undef\s+SIMDJSON_CONDITIONAL_INCLUDE\s*$', line):
-                    assert not file.is_conditional_include, "SIMDJSON_CONDITIONAL_INCLUDE undefined in amalgamated file {file}! Not allowed."
+                    assert not file.is_conditional_include, "SIMDJSON_CONDITIONAL_INCLUDE undefined in amalgamated file {file}! Not allowed. {rules}"
-                    assert self.in_conditional_include_block, f"{file} undefines SIMDJSON_CONDITIONAL_INCLUDE without defining it"
+                    assert self.in_conditional_include_block, f"{file} undefines SIMDJSON_CONDITIONAL_INCLUDE without defining it {rules}"
                     self.write(f'/* undefining SIMDJSON_CONDITIONAL_INCLUDE */')
                     self.in_conditional_include_block = False
 
                 self.write(line)
 
-            assert not self.editor_only_region, f"{file} ended without #endif // SIMDJSON_CONDITIONAL_INCLUDE"
+            assert not self.editor_only_region, f"{file} ended without #endif // SIMDJSON_CONDITIONAL_INCLUDE {rules}"
 
         self.write(f"/* end file {self.file_to_str(file)} */")
 

singleheader/simdjson.cpp

@@ -1,4 +1,4 @@
-/* auto-generated on 2024-09-17 15:48:50 -0400. Do not edit! */
+/* auto-generated on 2024-10-28 20:27:26 -0400. Do not edit! */
 /* including simdjson.cpp:  */
 /* begin file simdjson.cpp */
 #define SIMDJSON_SRC_SIMDJSON_CPP
@@ -77,6 +77,18 @@
 #endif
 #endif
 
+#ifdef __has_include
+#if __has_include(<version>)
+#include <version>
+#endif
+#endif
+
+#ifdef __cpp_concepts
+#include <utility>
+#define SIMDJSON_SUPPORTS_DESERIALIZATION 1
+#else // __cpp_concepts
+#define SIMDJSON_SUPPORTS_DESERIALIZATION 0
+#endif
 #endif // SIMDJSON_COMPILER_CHECK_H
 /* end file simdjson/compiler_check.h */
 /* including simdjson/portability.h: #include "simdjson/portability.h" */
@@ -2431,7 +2443,8 @@ enum error_code {
   SCALAR_DOCUMENT_AS_VALUE,   ///< A scalar document is treated as a value.
   OUT_OF_BOUNDS,              ///< Attempted to access location outside of document.
   TRAILING_CONTENT,           ///< Unexpected trailing content in the JSON input
-  NUM_ERROR_CODES
+  OUT_OF_CAPACITY,            ///< The capacity was exceeded, we cannot allocate enough memory.
+  NUM_ERROR_CODES             ///< Placeholder for end of error code list.
 };
 
 /**
@@ -2700,6 +2713,122 @@ inline const std::string error_message(int error) noexcept;
 #endif // SIMDJSON_ERROR_H
 /* end file simdjson/error.h */
 /* skipped duplicate #include "simdjson/portability.h" */
+/* including simdjson/concepts.h: #include "simdjson/concepts.h" */
+/* begin file simdjson/concepts.h */
+#ifndef SIMDJSON_CONCEPTS_H
+#define SIMDJSON_CONCEPTS_H
+#if SIMDJSON_SUPPORTS_DESERIALIZATION
+
+#include <concepts>
+#include <type_traits>
+
+namespace simdjson {
+namespace concepts {
+
+namespace details {
+#define SIMDJSON_IMPL_CONCEPT(name, method)                                    \
+  template <typename T>                                                        \
+  concept supports_##name = !std::is_const_v<T> && requires {                  \
+    typename std::remove_cvref_t<T>::value_type;                               \
+    requires requires(typename std::remove_cvref_t<T>::value_type &&val,       \
+                      T obj) {                                                 \
+      obj.method(std::move(val));                                              \
+      requires !requires { obj = std::move(val); };                            \
+    };                                                                         \
+  };
+
+SIMDJSON_IMPL_CONCEPT(emplace_back, emplace_back);
+SIMDJSON_IMPL_CONCEPT(emplace, emplace);
+SIMDJSON_IMPL_CONCEPT(push_back, push_back);
+SIMDJSON_IMPL_CONCEPT(add, add);
+SIMDJSON_IMPL_CONCEPT(push, push);
+SIMDJSON_IMPL_CONCEPT(append, append);
+SIMDJSON_IMPL_CONCEPT(insert, insert);
+SIMDJSON_IMPL_CONCEPT(op_append, operator+=);
+
+#undef SIMDJSON_IMPL_CONCEPT
+} // namespace details
+
+/// Check if T is a container that we can append to, including:
+///   std::vector, std::deque, std::list, std::string, ...
+template <typename T>
+concept appendable_containers =
+    details::supports_emplace_back<T> || details::supports_emplace<T> ||
+    details::supports_push_back<T> || details::supports_push<T> ||
+    details::supports_add<T> || details::supports_append<T> ||
+    details::supports_insert<T>;
+
+/// Insert into the container however possible
+template <appendable_containers T, typename... Args>
+constexpr decltype(auto) emplace_one(T &vec, Args &&...args) {
+  if constexpr (details::supports_emplace_back<T>) {
+    return vec.emplace_back(std::forward<Args>(args)...);
+  } else if constexpr (details::supports_emplace<T>) {
+    return vec.emplace(std::forward<Args>(args)...);
+  } else if constexpr (details::supports_push_back<T>) {
+    return vec.push_back(std::forward<Args>(args)...);
+  } else if constexpr (details::supports_push<T>) {
+    return vec.push(std::forward<Args>(args)...);
+  } else if constexpr (details::supports_add<T>) {
+    return vec.add(std::forward<Args>(args)...);
+  } else if constexpr (details::supports_append<T>) {
+    return vec.append(std::forward<Args>(args)...);
+  } else if constexpr (details::supports_insert<T>) {
+    return vec.insert(std::forward<Args>(args)...);
+  } else if constexpr (details::supports_op_append<T> && sizeof...(Args) == 1) {
+    return vec.operator+=(std::forward<Args>(args)...);
+  } else {
+    static_assert(!sizeof(T *),
+                  "We don't know how to add things to this container");
+  }
+}
+
+/// This checks if the container will return a reference to the newly added
+/// element after an insert which for example `std::vector::emplace_back` does
+/// since C++17; this will allow some optimizations.
+template <typename T>
+concept returns_reference = appendable_containers<T> && requires {
+  typename std::remove_cvref_t<T>::reference;
+  requires requires(typename std::remove_cvref_t<T>::value_type &&val, T obj) {
+    {
+      emplace_one(obj, std::move(val))
+    } -> std::same_as<typename std::remove_cvref_t<T>::reference>;
+  };
+};
+
+template <typename T>
+concept smart_pointer = requires(std::remove_cvref_t<T> ptr) {
+  // Check if T has a member type named element_type
+  typename std::remove_cvref_t<T>::element_type;
+
+  // Check if T has a get() member function
+  {
+    ptr.get()
+  } -> std::same_as<typename std::remove_cvref_t<T>::element_type *>;
+
+  // Check if T can be dereferenced
+  { *ptr } -> std::same_as<typename std::remove_cvref_t<T>::element_type &>;
+};
+
+template <typename T>
+concept optional_type = requires(std::remove_cvref_t<T> obj) {
+  typename std::remove_cvref_t<T>::value_type;
+  { obj.value() } -> std::same_as<typename std::remove_cvref_t<T>::value_type&>;
+  requires requires(typename std::remove_cvref_t<T>::value_type &&val) {
+    obj.emplace(std::move(val));
+    obj = std::move(val);
+    {
+      obj.value_or(val)
+    } -> std::convertible_to<typename std::remove_cvref_t<T>::value_type>;
+  };
+  { static_cast<bool>(obj) } -> std::same_as<bool>; // convertible to bool
+};
+
+} // namespace concepts
+} // namespace simdjson
+#endif // SIMDJSON_SUPPORTS_DESERIALIZATION
+#endif // SIMDJSON_CONCEPTS_H
+/* end file simdjson/concepts.h */
 
 /**
  * @brief The top level simdjson namespace, containing everything the library provides.
@@ -6485,7 +6614,6 @@ extern SIMDJSON_DLLIMPORTEXPORT const uint64_t thintable_epi8[256];
 
 #endif // SIMDJSON_INTERNAL_SIMDPRUNE_TABLES_H
 /* end file simdjson/internal/simdprune_tables.h */
-
 #endif // SIMDJSON_GENERIC_DEPENDENCIES_H
 /* end file simdjson/generic/dependencies.h */
 /* including generic/dependencies.h: #include <generic/dependencies.h> */
@@ -14176,8 +14304,14 @@ static_assert(sizeof(__m256i) <= simdjson::SIMDJSON_PADDING, "insufficient paddi
 /* end file simdjson/haswell/intrinsics.h */
 
 #if !SIMDJSON_CAN_ALWAYS_RUN_HASWELL
+// We enable bmi2 only if LLVM/clang is used, because GCC may not
+// make good use of it. See https://github.com/simdjson/simdjson/pull/2243
+#if defined(__clang__)
+SIMDJSON_TARGET_REGION("avx2,bmi,bmi2,pclmul,lzcnt,popcnt")
+#else
 SIMDJSON_TARGET_REGION("avx2,bmi,pclmul,lzcnt,popcnt")
 #endif
+#endif
 
 /* including simdjson/haswell/bitmanipulation.h: #include "simdjson/haswell/bitmanipulation.h" */
 /* begin file simdjson/haswell/bitmanipulation.h */
@@ -16808,8 +16942,14 @@ static_assert(sizeof(__m256i) <= simdjson::SIMDJSON_PADDING, "insufficient paddi
 /* end file simdjson/haswell/intrinsics.h */
 
 #if !SIMDJSON_CAN_ALWAYS_RUN_HASWELL
+// We enable bmi2 only if LLVM/clang is used, because GCC may not
+// make good use of it. See https://github.com/simdjson/simdjson/pull/2243
+#if defined(__clang__)
+SIMDJSON_TARGET_REGION("avx2,bmi,bmi2,pclmul,lzcnt,popcnt")
+#else
 SIMDJSON_TARGET_REGION("avx2,bmi,pclmul,lzcnt,popcnt")
 #endif
+#endif
 
 /* including simdjson/haswell/bitmanipulation.h: #include "simdjson/haswell/bitmanipulation.h" */
 /* begin file simdjson/haswell/bitmanipulation.h */

src/arm64.cpp

@@ -164,6 +164,10 @@ simdjson_warn_unused error_code dom_parser_implementation::parse(const uint8_t *
   return stage2(_doc);
 }
 
+simdjson_warn_unused size_t implementation::write_string_escaped(const std::string_view input, char *out) const noexcept {
+  return arm64::stringparsing::write_string_escaped(input, out);
+}
+
 } // namespace arm64
 } // namespace simdjson
 

src/fallback.cpp

@@ -402,6 +402,10 @@ simdjson_warn_unused error_code dom_parser_implementation::parse(const uint8_t *
   return stage2(_doc);
 }
 
+simdjson_warn_unused size_t implementation::write_string_escaped(const std::string_view input, char *out) const noexcept {
+  return fallback::stringparsing::write_string_escaped(input, out);
+}
+
 } // namespace fallback
 } // namespace simdjson
 

src/generic/stage2/stringparsing.h

@@ -236,6 +236,101 @@ simdjson_warn_unused simdjson_inline uint8_t *parse_wobbly_string(const uint8_t
   }
 }
 
+simdjson_warn_unused size_t write_string_escaped(const std::string_view input, char *out) noexcept {
+  // We are making the following assumption: most strings will either be very short or they will not
+  // need escaping.
+  size_t i = 0;
+  size_t pos = 0;
+  if(input.size() >= escaping::BYTES_PROCESSED) {
+    auto vec_processing = [input,out]() -> size_t {
+      size_t i = 0;
+      size_t pos = 0;
+      for(;input.size() - i >= escaping::BYTES_PROCESSED; i += escaping::BYTES_PROCESSED) {
+        escaping vinput = escaping::copy_and_find(reinterpret_cast<const uint8_t *>(input.data()) + i, reinterpret_cast<uint8_t *>(out) + pos);
+        if(vinput.has_escape()) {
+          return i + vinput.escape_index(); // We have a character that needs escaping
+        }
+        pos += escaping::BYTES_PROCESSED;
+      }
+      if(i == input.size()) { return input.size(); }
+      // We virtually backtrack so we can load a full vector register
+      i = input.size() - escaping::BYTES_PROCESSED;
+      pos = i;
+      escaping vinput = escaping::copy_and_find(reinterpret_cast<const uint8_t *>(input.data()) + i, reinterpret_cast<uint8_t *>(out) + pos);
+      if(vinput.has_escape()) {
+        return i + vinput.escape_index(); // We have a character that needs escaping
+      }
+      return input.size();
+    };
+    i = vec_processing();
+    pos = i;
+    if(i == input.size()) { return pos; }
+    // Here we only continue if there was a character that needed escaping.
+  }
+  static std::string_view control_chars[] = {
+    "\\x0000", "\\x0001", "\\x0002", "\\x0003", "\\x0004", "\\x0005", "\\x0006",
+    "\\x0007", "\\x0008", "\\t",     "\\n",     "\\x000b", "\\f",     "\\r",
+    "\\x000e", "\\x000f", "\\x0010", "\\x0011", "\\x0012", "\\x0013", "\\x0014",
+    "\\x0015", "\\x0016", "\\x0017", "\\x0018", "\\x0019", "\\x001a", "\\x001b",
+    "\\x001c", "\\x001d", "\\x001e", "\\x001f"};
+  static std::array<uint8_t, 256> json_quotable_character =
+    []() constexpr {
+      std::array<uint8_t, 256> result{};
+      for (int i = 0; i < 32; i++) {
+        result[i] = 1;
+      }
+      for (int i : {'"', '\\'}) {
+        result[i] = 1;
+      }
+      return result;
+    }();
+  // The rest could possibly be vectorized, but consider that we expect most strings
+  // to be short or not to require escaping.
+  for (; i < input.size(); i++) {
+    uint8_t c = static_cast<uint8_t>(input[i]);
+    if(json_quotable_character[c]) {
+      switch (c) {
+      case '"':
+        out[pos++] = '\\';
+        out[pos++] = '"';
+        break;
+      case '\\':
+        out[pos++] = '\\';
+        out[pos++] = '\\';
+        break;
+      case '\b':
+        out[pos++] = '\\';
+        out[pos++] = 'b';
+        break;
+      case '\f':
+        out[pos++] = '\\';
+        out[pos++] = 'f';
+        break;
+      case '\n':
+        out[pos++] = '\\';
+        out[pos++] = 'n';
+        break;
+      case '\r':
+        out[pos++] = '\\';
+        out[pos++] = 'r';
+        break;
+      case '\t':
+        out[pos++] = '\\';
+        out[pos++] = 't';
+        break;
+      default:
+        control_chars[c].copy(out + pos, 6);
+        pos += 6;
+      }
+    } else {
+      out[pos++] = c;
+    }
+  }
+  return pos;
+}
+
+
+
 } // namespace stringparsing
 } // unnamed namespace
 } // namespace SIMDJSON_IMPLEMENTATION

src/haswell.cpp

@@ -161,6 +161,10 @@ simdjson_warn_unused error_code dom_parser_implementation::parse(const uint8_t *
   return stage2(_doc);
 }
 
+simdjson_warn_unused size_t implementation::write_string_escaped(const std::string_view input, char *out) const noexcept {
+  return haswell::stringparsing::write_string_escaped(input, out);
+}
+
 } // namespace SIMDJSON_IMPLEMENTATION
 } // namespace simdjson
 

src/icelake.cpp

@@ -207,6 +207,10 @@ simdjson_warn_unused error_code dom_parser_implementation::parse(const uint8_t *
   return stage2(_doc);
 }
 
+simdjson_warn_unused size_t implementation::write_string_escaped(const std::string_view input, char *out) const noexcept {
+  return icelake::stringparsing::write_string_escaped(input, out);
+}
+
 } // namespace icelake
 } // namespace simdjson
 

src/implementation.cpp

@@ -186,6 +186,9 @@ public:
   simdjson_warn_unused bool validate_utf8(const char * buf, size_t len) const noexcept final override {
     return set_best()->validate_utf8(buf, len);
   }
+  simdjson_warn_unused size_t write_string_escaped(const std::string_view input, char *out) const noexcept final {
+    return set_best()->write_string_escaped(input, out);
+  }
   simdjson_inline detect_best_supported_implementation_on_first_use() noexcept : implementation("best_supported_detector", "Detects the best supported implementation and sets it", 0) {}
 private:
   const implementation *set_best() const noexcept;
@@ -236,6 +239,9 @@ public:
   simdjson_warn_unused error_code minify(const uint8_t *, size_t, uint8_t *, size_t &) const noexcept final override {
     return UNSUPPORTED_ARCHITECTURE;
   }
+  simdjson_warn_unused size_t write_string_escaped(const std::string_view input, char *out) const noexcept final {
+    return 0;
+  }
   simdjson_warn_unused bool validate_utf8(const char *, size_t) const noexcept final override {
     return false; // Just refuse to validate. Given that we have a fallback implementation
     // it seems unlikely that unsupported_implementation will ever be used. If it is used,
@@ -319,6 +325,9 @@ simdjson_warn_unused error_code minify(const char *buf, size_t len, char *dst, s
 simdjson_warn_unused bool validate_utf8(const char *buf, size_t len) noexcept {
   return get_active_implementation()->validate_utf8(buf, len);
 }
+simdjson_warn_unused size_t write_string_escaped(const std::string_view input, char *out) noexcept {
+  return get_active_implementation()->write_string_escaped(input, out);
+}
 const implementation * builtin_implementation() {
   static const implementation * builtin_impl = get_available_implementations()[SIMDJSON_STRINGIFY(SIMDJSON_BUILTIN_IMPLEMENTATION)];
   assert(builtin_impl);

src/lasx.cpp

@@ -124,6 +124,10 @@ simdjson_warn_unused error_code dom_parser_implementation::parse(const uint8_t *
   return stage2(_doc);
 }
 
+simdjson_warn_unused size_t implementation::write_string_escaped(const std::string_view input, char *out) const noexcept {
+  return lasx::stringparsing::write_string_escaped(input, out);
+}
+
 } // namespace lasx
 } // namespace simdjson
 

src/lsx.cpp

@@ -128,6 +128,10 @@ simdjson_warn_unused error_code dom_parser_implementation::parse(const uint8_t *
   return stage2(_doc);
 }
 
+simdjson_warn_unused size_t implementation::write_string_escaped(const std::string_view input, char *out) const noexcept {
+  return lsx::stringparsing::write_string_escaped(input, out);
+}
+
 } // namespace lsx
 } // namespace simdjson
 

src/ppc64.cpp

@@ -134,6 +134,10 @@ simdjson_warn_unused error_code dom_parser_implementation::parse(const uint8_t *
   return stage2(_doc);
 }
 
+simdjson_warn_unused size_t implementation::write_string_escaped(const std::string_view input, char *out) const noexcept {
+  return ppc64::stringparsing::write_string_escaped(input, out);
+}
+
 } // namespace ppc64
 } // namespace simdjson
 

src/westmere.cpp

@@ -166,6 +166,10 @@ simdjson_warn_unused error_code dom_parser_implementation::parse(const uint8_t *
   return stage2(_doc);
 }
 
+simdjson_warn_unused size_t implementation::write_string_escaped(const std::string_view input, char *out) const noexcept {
+  return westmere::stringparsing::write_string_escaped(input, out);
+}
+
 } // namespace westmere
 } // namespace simdjson
 

tests/CMakeLists.txt

@@ -26,3 +26,4 @@ endif()
 add_cpp_test(checkimplementation LABELS other per_implementation)
 
 add_subdirectory(compilation_failure_tests)
+add_subdirectory(builder)

tests/builder/CMakeLists.txt

@@ -0,0 +1,12 @@
+# All remaining tests link with simdjson proper
+link_libraries(simdjson)
+include_directories(..)
+add_cpp_test(builder_string_builder_tests              LABELS ondemand acceptance per_implementation)
+
+# Copy the simdjson dll into the tests directory
+if(MSVC AND BUILD_SHARED_LIBS)
+  add_custom_command(TARGET builder_string_builder_tests POST_BUILD        # Adds a post-build event
+    COMMAND ${CMAKE_COMMAND} -E copy_if_different  # which executes "cmake -E copy_if_different..."
+        "$<TARGET_FILE:simdjson>"      # <--this is in-file
+        "$<TARGET_FILE_DIR:builder_string_builder_tests>")                 # <--this is out-file path
+endif(MSVC AND BUILD_SHARED_LIBS)

tests/builder/builder_string_builder_tests.cpp

@@ -0,0 +1,178 @@
+#include "simdjson.h"
+#include "test_builder.h"
+#include <string_view>
+
+using namespace simdjson;
+
+namespace builder_tests {
+  using namespace std;
+
+    #if SIMDJSON_EXCEPTIONS
+    bool string_convertion_except() {
+        TEST_START();
+        simdjson::ondemand::parser p;
+        simdjson::builder::string_builder sb;
+        sb.append('a');
+        std::string r(sb);
+        ASSERT_EQUAL(r, "a");
+        TEST_SUCCEED();
+    }
+    #endif
+
+
+    bool append_char() {
+        TEST_START();
+        simdjson::builder::string_builder sb;
+        sb.append('a');
+        ASSERT_EQUAL(sb.size(), 1);
+        std::string_view p;
+        auto result = sb.view().get(p);
+        ASSERT_EQUAL(result, SUCCESS);
+        ASSERT_EQUAL(p, "a");
+        TEST_SUCCEED();
+    }
+
+
+    bool append_integer() {
+        TEST_START();
+        simdjson::builder::string_builder sb;
+        sb.append(42);
+        ASSERT_EQUAL(sb.size(), 2);
+        std::string_view p;
+        auto result = sb.view().get(p);
+        ASSERT_EQUAL(result, SUCCESS);
+        ASSERT_EQUAL(p, "42");
+        TEST_SUCCEED();
+    }
+
+    bool append_float() {
+        TEST_START();
+        simdjson::builder::string_builder sb;
+        sb.append(1.1);
+        ASSERT_EQUAL(sb.size(), 3);
+        std::string_view p;
+        auto result = sb.view().get(p);
+        ASSERT_EQUAL(result, SUCCESS);
+        ASSERT_EQUAL(p, "1.1");
+        TEST_SUCCEED();
+    }
+
+    bool append_null() {
+        TEST_START();
+        simdjson::builder::string_builder sb;
+        sb.append_null();
+        ASSERT_EQUAL(sb.size(), 4);
+        std::string_view p;
+        auto result = sb.view().get(p);
+        ASSERT_EQUAL(result, SUCCESS);
+        ASSERT_EQUAL(p, "null");
+        TEST_SUCCEED();
+    }
+
+    bool clear() {
+        TEST_START();
+        simdjson::builder::string_builder sb;
+        sb.append('a');
+        sb.clear();
+        ASSERT_EQUAL(sb.size(), 0);
+        TEST_SUCCEED();
+    }
+
+    bool escape_and_append() {
+        TEST_START();
+        simdjson::builder::string_builder sb;
+        sb.escape_and_append("Hello, \"world\"!");
+        std::string_view p;
+        auto result = sb.view().get(p);
+        ASSERT_EQUAL(result, SUCCESS);
+        ASSERT_EQUAL(p, "Hello, \"world\"!");
+        TEST_SUCCEED();
+    }
+
+    bool escape_and_append_with_quotes() {
+        TEST_START();
+        simdjson::builder::string_builder sb;
+        sb.escape_and_append_with_quotes("Hello, \"world\"!");
+        std::string_view p;
+        auto result = sb.view().get(p);
+        ASSERT_EQUAL(result, SUCCESS);
+        ASSERT_EQUAL(p, "\"Hello, \\\"world\\\"!\"");
+        TEST_SUCCEED();
+    }
+
+    bool append_raw() {
+        TEST_START();
+        simdjson::builder::string_builder sb;
+        sb.append_raw("Test");
+        std::string_view p;
+        auto result = sb.view().get(p);
+        ASSERT_EQUAL(result, SUCCESS);
+        ASSERT_EQUAL(p, "Test");
+        TEST_SUCCEED();
+    }
+
+    bool raw_with_length() {
+        TEST_START();
+        simdjson::builder::string_builder sb;
+        sb.append_raw("Test String", 4);
+        std::string_view p;
+        auto result = sb.view().get(p);
+        ASSERT_EQUAL(result, SUCCESS);
+        ASSERT_EQUAL(p, "Test");
+        TEST_SUCCEED();
+    }
+
+    bool string_convertion() {
+        TEST_START();
+        simdjson::builder::string_builder sb;
+        sb.append('a');
+        std::string_view p;
+        auto result = sb.view().get(p);
+        ASSERT_EQUAL(result, SUCCESS);
+        ASSERT_EQUAL(p, "a");
+        TEST_SUCCEED();
+    }
+
+    bool unicode_validation() {
+        TEST_START();
+        simdjson::builder::string_builder sb;
+        sb.append('a');
+        ASSERT_TRUE(sb.validate_unicode());
+        TEST_SUCCEED();
+    }
+
+    bool buffer_growth() {
+        TEST_START();
+        simdjson::builder::string_builder sb;
+        for(int i = 0; i < 3; ++i) {
+            sb.append('a');
+        }
+        ASSERT_EQUAL(sb.size(), 3);
+        TEST_SUCCEED();
+    }
+
+    bool run() {
+        return
+    #if SIMDJSON_EXCEPTIONS
+            string_convertion_except() &&
+    #endif
+            append_char() &&
+            append_integer() &&
+            append_float() &&
+            append_null() &&
+            clear() &&
+            escape_and_append() &&
+            escape_and_append_with_quotes() &&
+            append_raw() &&
+            raw_with_length() &&
+            string_convertion() &&
+            buffer_growth() &&
+            unicode_validation() &&
+            true;
+    }
+
+} // namespace twitter_tests
+
+int main(int argc, char *argv[]) {
+  return test_main(argc, argv, builder_tests::run);
+}

tests/builder/test_builder.h

@@ -0,0 +1,51 @@
+#ifndef ONDEMAND_TEST_BUILDER_H
+#define ONDEMAND_TEST_BUILDER_H
+
+#include <iostream>
+#include <unistd.h>
+#include "simdjson.h"
+#include "cast_tester.h"
+#include "test_macros.h"
+
+template<typename F>
+int test_main(int argc, char *argv[], const F& test_function) {
+  std::cout << std::unitbuf;
+  int c;
+  while ((c = getopt(argc, argv, "a:")) != -1) {
+    switch (c) {
+    case 'a': {
+      const simdjson::implementation *impl = simdjson::get_available_implementations()[optarg];
+      if (!impl) {
+        std::fprintf(stderr, "Unsupported architecture value -a %s\n", optarg);
+        return EXIT_FAILURE;
+      }
+      simdjson::get_active_implementation() = impl;
+      break;
+    }
+    default:
+      std::fprintf(stderr, "Unexpected argument %c\n", c);
+      return EXIT_FAILURE;
+    }
+  }
+
+  // this is put here deliberately to check that the documentation is correct (README),
+  // should this fail to compile, you should update the documentation:
+  if (simdjson::get_active_implementation()->name() == "unsupported") {
+    std::printf("unsupported CPU\n");
+    std::abort();
+  }
+  // We want to know what we are testing.
+  std::cout << "builtin_implementation -- " << simdjson::builtin_implementation()->name() << std::endl;
+  std::cout << "------------------------------------------------------------" << std::endl;
+
+  std::cout << "Running tests." << std::endl;
+  if (test_function()) {
+    std::cout << "Success!" << std::endl;
+    return EXIT_SUCCESS;
+  } else {
+    std::cerr << "FAILED." << std::endl;
+    return EXIT_FAILURE;
+  }
+}
+
+#endif // ONDEMAND_TEST_BUILDER_H

tests/ondemand/CMakeLists.txt

@@ -2,6 +2,8 @@
 link_libraries(simdjson)
 include_directories(..)
 add_subdirectory(compilation_failure_tests)
+add_cpp_test(ondemand_car_tag_invoke_deserialization LABELS ondemand acceptance per_implementation)
+add_cpp_test(ondemand_car_deserialization            LABELS ondemand acceptance per_implementation)
 add_cpp_test(ondemand_log_tests                      LABELS ondemand acceptance per_implementation)
 add_cpp_test(ondemand_log_error_tests                LABELS ondemand acceptance per_implementation)
 add_cpp_test(ondemand_tostring_tests                 LABELS ondemand acceptance per_implementation)
@@ -28,6 +30,9 @@ add_cpp_test(ondemand_to_string              LABELS ondemand acceptance per_impl
 add_cpp_test(ondemand_twitter_tests                  LABELS ondemand acceptance per_implementation)
 add_cpp_test(ondemand_wrong_type_error_tests         LABELS ondemand acceptance per_implementation)
 add_cpp_test(ondemand_iterate_many_csv               LABELS ondemand acceptance per_implementation)
+add_cpp_test(ondemand_custom_types_tests             LABELS ondemand acceptance per_implementation)
+add_cpp_test(ondemand_custom_types_document_tests    LABELS ondemand acceptance per_implementation)
+add_cpp_test(ondemand_stl_types_tests                LABELS ondemand acceptance per_implementation)
 if(NOT SIMDJSON_SANITIZE)
   add_cpp_test(ondemand_cacheline              LABELS ondemand acceptance per_implementation)
 endif()

tests/ondemand/ondemand_car_deserialization.cpp

@@ -0,0 +1,263 @@
+#include "simdjson.h"
+#include "test_ondemand.h"
+#include <iostream>
+#include <vector>
+
+using namespace simdjson;
+
+/**
+ * A custom type that we want to parse.
+ */
+struct Car {
+  std::string make{};
+  std::string model{};
+  int64_t year{};
+  std::vector<double> tire_pressure{};
+  bool operator==(const Car &other) const {
+    return make == other.make && model == other.model && year == other.year &&
+           tire_pressure == other.tire_pressure;
+  }
+};
+
+std::ostream &operator<<(std::ostream &os, const Car &c) {
+  os << c.make << " " << c.model << " " << c.year << " ";
+  for (auto p : c.tire_pressure) {
+    os << p << " ";
+  }
+  return os;
+}
+
+#if !SIMDJSON_SUPPORTS_DESERIALIZATION
+// This code is not necessary if you have a C++20 compliant system:
+template <>
+simdjson_inline simdjson_result<std::vector<double>>
+simdjson::ondemand::value::get() noexcept {
+  ondemand::array array;
+  auto error = get_array().get(array);
+  if (error) {
+    return error;
+  }
+  std::vector<double> vec;
+  for (auto v : array) {
+    double val;
+    error = v.get_double().get(val);
+    if (error) {
+      return error;
+    }
+    vec.push_back(val);
+  }
+  return vec;
+}
+#endif
+
+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;
+  }
+  if ((error = obj["tire_pressure"].get<std::vector<double>>().get(
+           car.tire_pressure))) {
+    return error;
+  }
+  return car;
+}
+
+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;
+  }
+  if ((error = obj["tire_pressure"].get<std::vector<double>>().get(
+           car.tire_pressure))) {
+    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;
+  }
+  if ((error = obj["tire_pressure"].get<std::vector<double>>().get(
+           car.tire_pressure))) {
+    return error;
+  }
+  return car;
+}
+
+int main_should_compile(void) {
+  padded_string json =
+      R"( [ { "make": "Toyota", "model": "Camry",  "year": 2018,
+       "tire_pressure": [ 40.1, 39.9 ] },
+  { "make": "Kia",    "model": "Soul",   "year": 2012,
+       "tire_pressure": [ 30.1, 31.0 ] },
+  { "make": "Toyota", "model": "Tercel", "year": 1999,
+       "tire_pressure": [ 29.8, 30.0 ] }
+])"_padded;
+  ondemand::parser parser;
+  ondemand::document doc;
+  [[maybe_unused]] auto doc_error = parser.iterate(json).get(doc);
+  for (auto val : doc) {
+#if SIMDJSON_EXCEPTIONS
+    Car c(val); // an exception may be thrown
+#else
+    Car c;
+    if (auto error = val.get<Car>().get(c)) {
+      std::cerr << error << std::endl;
+      return EXIT_FAILURE;
+    }
+#endif
+  }
+  return EXIT_SUCCESS;
+}
+
+namespace car_error_tests {
+bool car_deserialize() {
+  TEST_START();
+  padded_string json =
+      R"( [ { "make": "Toyota", "model": "Camry",  "year": 2018,
+       "tire_pressure": [ 40.1, 39.9 ] },
+  { "make": "Kia",    "model": "Soul",   "year": 2012,
+       "tire_pressure": [ 30.1, 31.0 ] },
+  { "make": "Toyota", "model": "Tercel", "year": 1999,
+       "tire_pressure": [ 29.8, 30.0 ] }
+])"_padded;
+  ondemand::parser parser;
+  ondemand::document doc;
+  [[maybe_unused]] auto doc_error = parser.iterate(json).get(doc);
+  std::vector<Car> cars;
+  for (auto val : doc) {
+#if SIMDJSON_EXCEPTIONS
+    Car c(val); // an exception may be thrown
+#else
+    Car c;
+    if (auto error = val.get<Car>().get(c)) {
+      std::cerr << error << std::endl;
+      return EXIT_FAILURE;
+    }
+#endif
+    cars.push_back(c);
+    std::cout << c.make << std::endl;
+  }
+  std::vector<Car> expected = {{"Toyota", "Camry", 2018, {40.1, 39.9}},
+                               {"Kia", "Soul", 2012, {30.1, 31.0}},
+                               {"Toyota", "Tercel", 1999, {29.8, 30.0}}};
+  ASSERT_EQUAL(cars.size(), expected.size());
+  for (size_t i = 0; i < cars.size(); i++) {
+    ASSERT_EQUAL(cars[i], expected[i]);
+  }
+  TEST_SUCCEED();
+}
+
+bool car_doc_deserialize() {
+  TEST_START();
+  padded_string json = R"(  { "make": "Toyota", "model": "Camry",  "year": 2018,
+       "tire_pressure": [ 40.1, 39.9 ] }
+)"_padded;
+  ondemand::parser parser;
+  ondemand::document doc;
+  [[maybe_unused]] auto doc_error = parser.iterate(json).get(doc);
+#if SIMDJSON_EXCEPTIONS
+  Car c(doc);   // an exception may be thrown
+#else
+  Car c;
+  if (auto error = doc.get<Car>().get(c)) {
+    std::cerr << error << std::endl;
+    return EXIT_FAILURE;
+  }
+#endif
+  Car expected = {"Toyota", "Camry", 2018, {40.1, 39.9}};
+  ASSERT_EQUAL(c, expected);
+  TEST_SUCCEED();
+}
+
+bool car_stream_deserialize() {
+  TEST_START();
+  padded_string json =
+      R"( { "make": "Toyota", "model": "Camry",  "year": 2018,
+       "tire_pressure": [ 40.1, 39.9 ] }
+  { "make": "Kia",    "model": "Soul",   "year": 2012,
+       "tire_pressure": [ 30.1, 31.0 ] }
+  { "make": "Toyota", "model": "Tercel", "year": 1999,
+       "tire_pressure": [ 29.8, 30.0 ] }
+)"_padded;
+  ondemand::parser parser;
+  ondemand::document_stream stream;
+  auto error = parser.iterate_many(json).get(stream);
+  if(error) {
+    std::cerr << error << std::endl;
+    return EXIT_FAILURE;
+  }
+  std::vector<Car> cars;
+
+#if SIMDJSON_EXCEPTIONS
+  for(ondemand::document_reference doc : stream) {
+    //Car c(doc);   // an exception may be thrown
+    cars.push_back(Car(doc)); // an exception may be thrown
+  }
+#else
+  for(auto doc : stream) {
+    Car c;
+    if ((error = doc.get<Car>().get(c))) {
+      std::cerr << error << std::endl;
+      return EXIT_FAILURE;
+    }
+    cars.push_back(c);
+  }
+#endif
+  std::vector<Car> expected = {{"Toyota", "Camry", 2018, {40.1, 39.9}},
+                               {"Kia", "Soul", 2012, {30.1, 31.0}},
+                               {"Toyota", "Tercel", 1999, {29.8, 30.0}}};
+  ASSERT_EQUAL(cars.size(), expected.size());
+  for (size_t i = 0; i < cars.size(); i++) {
+    ASSERT_EQUAL(cars[i], expected[i]);
+  }
+  TEST_SUCCEED();
+}
+
+bool run() { return car_stream_deserialize() && car_doc_deserialize() && car_deserialize(); }
+} // namespace car_error_tests
+
+int main(int argc, char *argv[]) {
+  return test_main(argc, argv, car_error_tests::run);
+}

tests/ondemand/ondemand_car_tag_invoke_deserialization.cpp

@@ -0,0 +1,335 @@
+#include "simdjson.h"
+#include "test_ondemand.h"
+#include <cstdlib>
+#include <iostream>
+#include <vector>
+#include <list>
+#include <optional>
+
+using namespace simdjson;
+
+#if !SIMDJSON_SUPPORTS_DESERIALIZATION
+
+int main(void) {
+  printf("This test is only relevant when SIMDJSON_SUPPORTS_DESERIALIZATION is true (C++20)\n");
+  return EXIT_SUCCESS;
+}
+#else
+
+/**
+ * A custom type that we want to parse.
+ */
+struct Car {
+  std::string make{};
+  std::string model{};
+  int year{};
+  std::vector<float> tire_pressure{};
+  bool operator==(const Car &other) const {
+    return make == other.make && model == other.model && year == other.year &&
+           tire_pressure == other.tire_pressure;
+  }
+};
+
+std::ostream &operator<<(std::ostream &os, const Car &c) {
+  os << c.make << " " << c.model << " " << c.year << " ";
+  for (auto p : c.tire_pressure) {
+    os << p << " ";
+  }
+  return os;
+}
+
+
+
+namespace simdjson {
+// This tag_invoke MUST be inside simdjson namespace
+template <typename simdjson_value>
+auto tag_invoke(deserialize_tag, simdjson_value &val, Car& car) {
+  ondemand::object obj;
+  auto error = val.get_object().get(obj);
+  if (error) {
+    return error;
+  }
+  if ((error = obj["make"].get_string(car.make))) {
+    return error;
+  }
+  if ((error = obj["model"].get_string(car.model))) {
+    return error;
+  }
+  if ((error = obj["year"].get(car.year))) {
+    return error;
+  }
+  if ((error = obj["tire_pressure"].get<std::vector<float>>().get(
+           car.tire_pressure))) {
+    return error;
+  }
+  return simdjson::SUCCESS;
+}
+
+// suppose we want to filter out all Toyotas
+template <typename simdjson_value>
+auto tag_invoke(deserialize_tag, simdjson_value &val, std::list<Car>& car) {
+  ondemand::array arr;
+  auto error = val.get_array().get(arr);
+  if (error) {
+    return error;
+  }
+  for (auto v : arr) {
+    Car c;
+    if ((error = v.get<Car>().get(c))) {
+      return error;
+    }
+    if(c.make != "Toyota") {
+      car.push_back(c);
+    }
+  }
+  return simdjson::SUCCESS;
+}
+} // namespace simdjson
+
+
+int main_should_compile(void) {
+  padded_string json =
+      R"( [ { "make": "Toyota", "model": "Camry",  "year": 2018,
+       "tire_pressure": [ 40.1, 39.9 ] },
+  { "make": "Kia",    "model": "Soul",   "year": 2012,
+       "tire_pressure": [ 30.1, 31.0 ] },
+  { "make": "Toyota", "model": "Tercel", "year": 1999,
+       "tire_pressure": [ 29.8, 30.0 ] }
+])"_padded;
+  ondemand::parser parser;
+  ondemand::document doc;
+  [[maybe_unused]] auto doc_error = parser.iterate(json).get(doc);
+  for (auto val : doc) {
+#if SIMDJSON_EXCEPTIONS
+    Car c(val); // an exception may be thrown
+#else
+    Car c;
+    if (auto error = val.get<Car>().get(c)) {
+      std::cerr << error << std::endl;
+      return EXIT_FAILURE;
+    }
+#endif
+  }
+  return EXIT_SUCCESS;
+}
+
+namespace car_error_tests {
+bool car_deserialize() {
+  TEST_START();
+  padded_string json =
+      R"( [ { "make": "Toyota", "model": "Camry",  "year": 2018,
+       "tire_pressure": [ 40.1, 39.9 ] },
+  { "make": "Kia",    "model": "Soul",   "year": 2012,
+       "tire_pressure": [ 30.1, 31.0 ] },
+  { "make": "Toyota", "model": "Tercel", "year": 1999,
+       "tire_pressure": [ 29.8, 30.0 ] }
+])"_padded;
+  ondemand::parser parser;
+  ondemand::document doc;
+  [[maybe_unused]] auto doc_error = parser.iterate(json).get(doc);
+  std::vector<Car> cars;
+  for (auto val : doc) {
+#if SIMDJSON_EXCEPTIONS
+    Car c(val); // an exception may be thrown
+#else
+    Car c;
+    if (auto error = val.get<Car>().get(c)) {
+      std::cerr << error << std::endl;
+      return EXIT_FAILURE;
+    }
+#endif
+    cars.push_back(c);
+    std::cout << c.make << std::endl;
+  }
+  std::vector<Car> expected = {{"Toyota", "Camry", 2018, {40.1f, 39.9f}},
+                               {"Kia", "Soul", 2012, {30.1f, 31.0f}},
+                               {"Toyota", "Tercel", 1999, {29.8f, 30.0f}}};
+  ASSERT_EQUAL(cars.size(), expected.size());
+  for (size_t i = 0; i < cars.size(); i++) {
+    ASSERT_EQUAL(cars[i], expected[i]);
+  }
+  TEST_SUCCEED();
+}
+
+bool vector_car_deserialize() {
+  TEST_START();
+  padded_string json =
+      R"( [ { "make": "Toyota", "model": "Camry",  "year": 2018,
+       "tire_pressure": [ 40.1, 39.9 ] },
+  { "make": "Kia",    "model": "Soul",   "year": 2012,
+       "tire_pressure": [ 30.1, 31.0 ] },
+  { "make": "Toyota", "model": "Tercel", "year": 1999,
+       "tire_pressure": [ 29.8, 30.0 ] }
+])"_padded;
+  ondemand::parser parser;
+  ondemand::document doc;
+  [[maybe_unused]] auto doc_error = parser.iterate(json).get(doc);
+#if SIMDJSON_EXCEPTIONS
+#if SIMDJSON_REGULAR_VISUAL_STUDIO
+  std::vector<Car> cars = doc.get<std::vector<Car>>();  // an exception may be thrown
+#else
+  std::vector<Car> cars(doc); // an exception may be thrown
+#endif
+#else
+  std::vector<Car> cars;
+  if (auto error = doc.get<std::vector<Car>>().get(cars)) {
+    std::cerr << error << std::endl;
+    return EXIT_FAILURE;
+  }
+#endif
+  std::vector<Car> expected = {{"Toyota", "Camry", 2018, {40.1f, 39.9f}},
+                               {"Kia", "Soul", 2012, {30.1f, 31.0f}},
+                               {"Toyota", "Tercel", 1999, {29.8f, 30.0f}}};
+  ASSERT_EQUAL(cars.size(), expected.size());
+  for (size_t i = 0; i < cars.size(); i++) {
+    ASSERT_EQUAL(cars[i], expected[i]);
+  }
+  TEST_SUCCEED();
+}
+
+
+bool list_car_deserialize() {
+  TEST_START();
+  padded_string json =
+      R"( [ { "make": "Toyota", "model": "Camry",  "year": 2018,
+       "tire_pressure": [ 40.1, 39.9 ] },
+  { "make": "Kia",    "model": "Soul",   "year": 2012,
+       "tire_pressure": [ 30.1, 31.0 ] },
+  { "make": "Toyota", "model": "Tercel", "year": 1999,
+       "tire_pressure": [ 29.8, 30.0 ] }
+])"_padded;
+  ondemand::parser parser;
+  ondemand::document doc;
+  [[maybe_unused]] auto doc_error = parser.iterate(json).get(doc);
+#if SIMDJSON_EXCEPTIONS
+#if SIMDJSON_REGULAR_VISUAL_STUDIO
+  std::list<Car> cars = doc.get<std::list<Car>>();  // an exception may be thrown
+#else
+  std::list<Car> cars(doc); // an exception may be thrown
+#endif
+#else
+  std::list<Car> cars;
+  if (auto error = doc.get<std::list<Car>>().get(cars)) {
+    std::cerr << error << std::endl;
+    return EXIT_FAILURE;
+  }
+#endif
+  std::list<Car> expected = {{"Kia", "Soul", 2012, {30.1f, 31.0f}}};
+  ASSERT_EQUAL(cars.size(), expected.size());
+  ASSERT_EQUAL(cars.front(), expected.front());
+  TEST_SUCCEED();
+}
+
+bool optional_car_deserialize() {
+  TEST_START();
+  padded_string json =
+      R"( { "car1": { "make": "Toyota", "model": "Camry",  "year": 2018,
+       "tire_pressure": [ 40.1, 39.9 ] }
+})"_padded;
+  ondemand::parser parser;
+  ondemand::document doc;
+  [[maybe_unused]] auto error = parser.iterate(json).get(doc);
+  std::optional<Car> car;
+  error = doc["key not found"].get<std::optional<Car>>().get(car);
+  ASSERT_TRUE(!car);
+  error = doc["car1"].get<std::optional<Car>>().get(car);
+  std::optional<Car> expected = Car{"Toyota", "Camry", 2018, {40.1f, 39.9f}};
+  ASSERT_TRUE(car == expected);
+  TEST_SUCCEED();
+}
+
+bool car_doc_deserialize() {
+  TEST_START();
+  padded_string json = R"(  { "make": "Toyota", "model": "Camry",  "year": 2018,
+       "tire_pressure": [ 40.1, 39.9 ] }
+)"_padded;
+  ondemand::parser parser;
+  ondemand::document doc;
+  [[maybe_unused]] auto doc_error = parser.iterate(json).get(doc);
+#if SIMDJSON_EXCEPTIONS
+  Car c(doc);   // an exception may be thrown
+#else
+  Car c;
+  if (auto error = doc.get<Car>().get(c)) {
+    std::cerr << error << std::endl;
+    return EXIT_FAILURE;
+  }
+#endif
+  Car expected = {"Toyota", "Camry", 2018, {40.1f, 39.9f}};
+  ASSERT_EQUAL(c, expected);
+  TEST_SUCCEED();
+}
+
+
+bool car_stream_deserialize() {
+  TEST_START();
+  padded_string json =
+      R"( { "make": "Toyota", "model": "Camry",  "year": 2018,
+       "tire_pressure": [ 40.1, 39.9 ] }
+  { "make": "Kia",    "model": "Soul",   "year": 2012,
+       "tire_pressure": [ 30.1, 31.0 ] }
+  { "make": "Toyota", "model": "Tercel", "year": 1999,
+       "tire_pressure": [ 29.8, 30.0 ] }
+)"_padded;
+  ondemand::parser parser;
+  ondemand::document_stream stream;
+  [[maybe_unused]] auto error = parser.iterate_many(json).get(stream);
+  std::vector<Car> cars;
+
+#if SIMDJSON_EXCEPTIONS
+  for(auto doc : stream) {
+    cars.push_back((Car)doc); // an exception may be thrown
+  }
+#else
+  for(auto doc : stream) {
+    Car c;
+    if ((error = doc.get<Car>().get(c))) {
+      std::cerr << error << std::endl;
+      return EXIT_FAILURE;
+    }
+    cars.push_back(c);
+  }
+#endif
+  std::vector<Car> expected = {{"Toyota", "Camry", 2018, {40.1f, 39.9f}},
+                               {"Kia", "Soul", 2012, {30.1f, 31.0f}},
+                               {"Toyota", "Tercel", 1999, {29.8f, 30.0f}}};
+  ASSERT_EQUAL(cars.size(), expected.size());
+  for (size_t i = 0; i < cars.size(); i++) {
+    ASSERT_EQUAL(cars[i], expected[i]);
+  }
+  TEST_SUCCEED();
+}
+
+bool car_unique_ptr_deserialize() {
+  TEST_START();
+  auto const json = R"( { "make": "Toyota", "model": "Camry",  "year": 2018,
+       "tire_pressure": [ 40.1, 39.9 ] })"_padded;
+  simdjson::ondemand::parser parser;
+  simdjson::ondemand::document doc;
+  [[maybe_unused]] auto error = parser.iterate(json).get(doc);
+#if SIMDJSON_EXCEPTIONS
+  std::unique_ptr<Car> c(doc);
+#else
+  std::unique_ptr<Car> c;
+  if ((error = doc.get<std::unique_ptr<Car>>().get(c))) {
+    std::cerr << error << std::endl;
+    return EXIT_FAILURE;
+  }
+#endif
+  ASSERT_EQUAL(c->make, "Toyota");
+  TEST_SUCCEED();
+}
+
+bool run() { return list_car_deserialize()
+                    && optional_car_deserialize()
+                    && car_unique_ptr_deserialize()
+                    && vector_car_deserialize()
+                    && car_stream_deserialize()
+                    && car_doc_deserialize()
+                    && car_deserialize(); }
+} // namespace car_error_tests
+
+int main(int argc, char *argv[]) {
+  return test_main(argc, argv, car_error_tests::run);
+}
+#endif // SIMDJSON_SUPPORTS_DESERIALIZATION

tests/ondemand/ondemand_custom_types_document_tests.cpp

@@ -0,0 +1,178 @@
+#include "simdjson.h"
+#include "test_ondemand.h"
+
+#include <string>
+#include <vector>
+
+
+namespace doc_custom_types_tests {
+#if SIMDJSON_EXCEPTIONS && defined(__cpp_concepts)
+struct Car {
+  std::string make{};
+  std::string model{};
+  int64_t year{};
+  std::vector<double> tire_pressure{};
+
+  friend error_code tag_invoke(simdjson::deserialize_tag,
+                                         auto &val, Car& car) {
+    simdjson::ondemand::object obj;
+    if (auto const error = val.get_object().get(obj)) {
+      return error;
+    }
+    // Instead of repeatedly obj["something"], we iterate through the object
+    // which we expect to be faster.
+    for (auto field : obj) {
+      simdjson::ondemand::raw_json_string key;
+      if (auto const error = field.key().get(key)) {
+        return error;
+      }
+      if (key == "make") {
+        if (auto const error = field.value().get_string(car.make)) {
+          return error;
+        }
+      } else if (key == "model") {
+        if (auto const error = field.value().get_string(car.model)) {
+          return error;
+        }
+      } else if (key == "year") {
+        if (auto const error = field.value().get_int64().get(car.year)) {
+          return error;
+        }
+      } else if (key == "tire_pressure") {
+        if (auto const error = field.value().get<std::vector<double>>().get(
+                car.tire_pressure)) {
+          return error;
+        }
+      }
+    }
+    return error_code::SUCCESS;
+  }
+};
+
+static_assert(simdjson::custom_deserializable<std::unique_ptr<Car>, simdjson::ondemand::value>, "It should be invocable");
+static_assert(simdjson::custom_deserializable<std::unique_ptr<Car>, simdjson::ondemand::document>, "Tag_invoke should work with document as well.");
+static_assert(simdjson::custom_deserializable<std::vector<Car>, simdjson::ondemand::value>, "It should be invocable");
+static_assert(simdjson::custom_deserializable<std::vector<Car>, simdjson::ondemand::document>, "Tag_invoke should work with document as well.");
+
+bool custom_test() {
+  TEST_START();
+  auto const json = R"( {
+      "make": "Toyota",
+      "model": "Camry",
+      "year": 2018,
+      "tire_pressure": [ 40.1, 39.9 ]
+ } )"_padded;
+
+  simdjson::ondemand::parser parser;
+  simdjson::ondemand::document doc = parser.iterate(json);
+
+  // creating car directly from "doc":
+  const std::unique_ptr<Car> car(doc);
+  if (car->make != "Toyota") {
+    return false;
+  }
+  if (car->model != "Camry") {
+    return false;
+  }
+  if (car->year != 2018) {
+    return false;
+  }
+  if (car->tire_pressure.size() != 2) {
+    return false;
+  }
+  TEST_SUCCEED();
+}
+
+bool readme_test() {
+  TEST_START();
+  auto const json = R"( { "make": "Toyota", "model": "Camry",  "year": 2018,
+       "tire_pressure": [ 40.1, 39.9 ] })"_padded;
+  simdjson::ondemand::parser parser;
+  simdjson::ondemand::document doc = parser.iterate(json);
+  std::unique_ptr<Car> c(doc);
+  std::cout << c->make << std::endl;
+  TEST_SUCCEED();
+}
+
+
+bool simple_document_test() {
+  TEST_START();
+  simdjson::padded_string json =
+      R"( { "make": "Toyota", "model": "Camry",  "year": 2018,
+       "tire_pressure": [ 40.1, 39.9 ] })"_padded;
+  simdjson::ondemand::parser parser;
+  simdjson::ondemand::document doc = parser.iterate(json);
+  Car c(doc);
+  std::cout << c.make << std::endl;
+  ASSERT_EQUAL(c.make, "Toyota");
+  TEST_SUCCEED();
+}
+
+bool custom_test_crazier() {
+  TEST_START();
+  simdjson::padded_string json =
+      R"( [ { "make": "Toyota", "model": "Camry",  "year": 2018,
+       "tire_pressure": [ 40.1, 39.9 ] },
+  { "make": "Kia",    "model": "Soul",   "year": 2012,
+       "tire_pressure": [ 30.1, 31.0 ] },
+  { "make": "Toyota", "model": "Tercel", "year": 1999,
+       "tire_pressure": [ 29.8, 30.0 ] }
+])"_padded;
+
+  simdjson::ondemand::parser parser;
+  simdjson::ondemand::document doc = parser.iterate(json);
+#if SIMDJSON_REGULAR_VISUAL_STUDIO
+  std::vector<Car> cars = doc.get<std::vector<Car>>();
+#else
+  std::vector<Car> cars(doc);
+#endif
+  for(Car& c : cars) {
+    std::cout << c.year << std::endl;
+    if (c.make != "Toyota" && c.make != "Kia") {
+      return false;
+    }
+    if (c.model != "Camry" && c.model != "Soul" && c.model != "Tercel") {
+      return false;
+    }
+    if (c.year != 2018 && c.year != 2012 && c.year != 1999) {
+      return false;
+    }
+    if (c.tire_pressure.size() != 2) {
+      return false;
+    }
+  }
+  TEST_SUCCEED();
+}
+
+bool simple_document_test_no_except() {
+  TEST_START();
+  simdjson::padded_string json =
+      R"( { "make": "Toyota", "model": "Camry",  "year": 2018,
+       "tire_pressure": [ 40.1, 39.9 ] })"_padded;
+  simdjson::ondemand::parser parser;
+  simdjson::ondemand::document doc = parser.iterate(json);
+  Car c;
+  auto error = doc.get(c);
+  if(error) { std::cerr << simdjson::error_message(error); return false; }
+  std::cout << c.make << std::endl;
+  ASSERT_EQUAL(c.make, "Toyota");
+  TEST_SUCCEED();
+}
+#endif // SIMDJSON_EXCEPTIONS
+bool run() {
+  return
+#if SIMDJSON_EXCEPTIONS && defined(__cpp_concepts)
+      readme_test() &&
+      custom_test() &&
+      simple_document_test() &&
+      simple_document_test_no_except() &&
+      custom_test_crazier() &&
+#endif // SIMDJSON_EXCEPTIONS
+      true;
+}
+
+} // namespace doc_custom_types_tests
+
+int main(const int argc, char *argv[]) {
+  return test_main(argc, argv, doc_custom_types_tests::run);
+}

tests/ondemand/ondemand_custom_types_tests.cpp

@@ -0,0 +1,195 @@
+#include "simdjson.h"
+#include "test_ondemand.h"
+
+#include <string>
+#include <vector>
+
+
+namespace custom_types_tests {
+#if SIMDJSON_EXCEPTIONS && SIMDJSON_SUPPORTS_DESERIALIZATION
+struct Car {
+  std::string make{};
+  std::string model{};
+  int year{};
+  std::vector<double> tire_pressure{};
+
+  friend simdjson::error_code tag_invoke(simdjson::deserialize_tag, auto &val, Car& car) {
+    simdjson::ondemand::object obj;
+    auto error = val.get_object().get(obj);
+    if (error) {
+      return error;
+    }
+    // Instead of repeatedly obj["something"], we iterate through the object
+    // which we expect to be faster.
+    for (auto field : obj) {
+      simdjson::ondemand::raw_json_string key;
+      error = field.key().get(key);
+      if (error) {
+        return error;
+      }
+      if (key == "make") {
+        error = field.value().get_string(car.make);
+        if (error) {
+          return error;
+        }
+      } else if (key == "model") {
+        error = field.value().get_string(car.model);
+        if (error) {
+          return error;
+        }
+      } else if (key == "year") {
+        error = field.value().get(car.year);
+        if (error) {
+          return error;
+        }
+      } else if (key == "tire_pressure") {
+        error = field.value().get(car.tire_pressure);
+        if (error) {
+          return error;
+        }
+      }
+    }
+    return simdjson::SUCCESS;
+  }
+};
+
+static_assert(simdjson::custom_deserializable<std::unique_ptr<Car>>, "It should be deserializable");
+
+bool custom_uniqueptr_test() {
+  TEST_START();
+  simdjson::padded_string json =
+      R"( [ { "make": "Toyota", "model": "Camry",  "year": 2018,
+       "tire_pressure": [ 40.1, 39.9 ] },
+  { "make": "Kia",    "model": "Soul",   "year": 2012,
+       "tire_pressure": [ 30.1, 31.0 ] },
+  { "make": "Toyota", "model": "Tercel", "year": 1999,
+       "tire_pressure": [ 29.8, 30.0 ] }
+])"_padded;
+
+  simdjson::ondemand::parser parser;
+  simdjson::ondemand::document doc = parser.iterate(json);
+  for (auto val : doc) {
+    std::unique_ptr<Car> c(val);
+    if (c->make != "Toyota" && c->make != "Kia") {
+      return false;
+    }
+    if (c->model != "Camry" && c->model != "Soul" && c->model != "Tercel") {
+      return false;
+    }
+    if (c->year != 2018 && c->year != 2012 && c->year != 1999) {
+      return false;
+    }
+    if (c->tire_pressure.size() != 2) {
+      return false;
+    }
+  }
+
+  TEST_SUCCEED();
+}
+
+
+
+bool custom_test() {
+  TEST_START();
+  simdjson::padded_string json =
+      R"( [ { "make": "Toyota", "model": "Camry",  "year": 2018,
+       "tire_pressure": [ 40.1, 39.9 ] },
+  { "make": "Kia",    "model": "Soul",   "year": 2012,
+       "tire_pressure": [ 30.1, 31.0 ] },
+  { "make": "Toyota", "model": "Tercel", "year": 1999,
+       "tire_pressure": [ 29.8, 30.0 ] }
+])"_padded;
+
+  simdjson::ondemand::parser parser;
+  simdjson::ondemand::document doc = parser.iterate(json);
+  for (auto val : doc) {
+    Car c(val);
+    if (c.make != "Toyota" && c.make != "Kia") {
+      return false;
+    }
+    if (c.model != "Camry" && c.model != "Soul" && c.model != "Tercel") {
+      return false;
+    }
+    if (c.year != 2018 && c.year != 2012 && c.year != 1999) {
+      return false;
+    }
+    if (c.tire_pressure.size() != 2) {
+      return false;
+    }
+  }
+
+  TEST_SUCCEED();
+}
+
+
+
+bool custom_test_crazy() {
+  TEST_START();
+  simdjson::padded_string json =
+      R"( [ { "make": "Toyota", "model": "Camry",  "year": 2018,
+       "tire_pressure": [ 40.1, 39.9 ] },
+  { "make": "Kia",    "model": "Soul",   "year": 2012,
+       "tire_pressure": [ 30.1, 31.0 ] },
+  { "make": "Toyota", "model": "Tercel", "year": 1999,
+       "tire_pressure": [ 29.8, 30.0 ] }
+])"_padded;
+
+  simdjson::ondemand::parser parser;
+  simdjson::ondemand::document doc = parser.iterate(json);
+  for (auto val : doc) {
+    Car c(val);
+    std::cout << c.year << std::endl;
+    if (c.make != "Toyota" && c.make != "Kia") {
+      return false;
+    }
+    if (c.model != "Camry" && c.model != "Soul" && c.model != "Tercel") {
+      return false;
+    }
+    if (c.year != 2018 && c.year != 2012 && c.year != 1999) {
+      return false;
+    }
+    if (c.tire_pressure.size() != 2) {
+      return false;
+    }
+  }
+
+  TEST_SUCCEED();
+}
+
+bool custom_no_except() {
+  TEST_START();
+  simdjson::padded_string json =
+      R"( [ { "make": "Toyota", "model": "Camry",  "year": 2018,
+       "tire_pressure": [ 40.1, 39.9 ] },
+  { "make": "Kia",    "model": "Soul",   "year": 2012,
+       "tire_pressure": [ 30.1, 31.0 ] },
+  { "make": "Toyota", "model": "Tercel", "year": 1999,
+       "tire_pressure": [ 29.8, 30.0 ] }
+])"_padded;
+
+  simdjson::ondemand::parser parser;
+  simdjson::ondemand::document doc = parser.iterate(json);
+  for (auto val : doc) {
+    Car c;
+    auto error = val.get(c);
+    if(error) { std::cerr << simdjson::error_message(error) << std::endl; return false; }
+  }
+
+  TEST_SUCCEED();
+}
+#endif // SIMDJSON_EXCEPTIONS
+bool run() {
+  return
+#if SIMDJSON_EXCEPTIONS && SIMDJSON_SUPPORTS_DESERIALIZATION
+      custom_test() &&
+      custom_uniqueptr_test() &&
+      custom_no_except() &&
+#endif // SIMDJSON_EXCEPTIONS
+      true;
+}
+
+} // namespace custom_types_tests
+
+int main(int argc, char *argv[]) {
+  return test_main(argc, argv, custom_types_tests::run);
+}

tests/ondemand/ondemand_readme_examples.cpp

@@ -49,6 +49,7 @@ struct Car {
   std::vector<double> tire_pressure;
 };
 
+#ifndef __cpp_concepts
 template <>
 simdjson_inline simdjson_result<std::vector<double>>
 simdjson::ondemand::value::get() noexcept {
@@ -66,7 +67,7 @@ simdjson::ondemand::value::get() noexcept {
   }
   return vec;
 }
-
+#endif
 
 
 template <>
@@ -75,29 +76,13 @@ simdjson_inline simdjson_result<Car> simdjson::ondemand::value::get() noexcept {
   auto error = get_object().get(obj);
   if (error) { return error; }
   Car car;
-  // Instead of repeatedly obj["something"], we iterate through the object which
+  if((error = obj["make"].get_string(car.make))) { return error; }
-  // we expect to be faster.
+  if((error = obj["model"].get_string(car.model))) { return error; }
-  for (auto field : obj) {
+  if((error = obj["year"].get_int64().get(car.year))) { return error; }
-    raw_json_string key;
+  if((error = obj["tire_pressure"].get<std::vector<double>>().get(car.tire_pressure))) { return error; }
-    if (error = field.key().get(key); error) { return error; }
-    if (key == "make") {
-      error = field.value().get_string(car.make);
-      if(error) { return error; }
-    } else if (key == "model") {
-      error = field.value().get_string(car.model);
-      if(error) { return error; }
-    } else if (key == "year") {
-      error = field.value().get_int64().get(car.year);
-      if(error) { return error; }
-    } else if (key == "tire_pressure") {
-      error = field.value().get<std::vector<double>>().get(car.tire_pressure);
-      if (error) { return error; }
-    }
-  }
   return car;
 }
 
-
 int custom_type_without_exceptions() {
   padded_string json = R"( [ { "make": "Toyota", "model": "Camry",  "year": 2018,
        "tire_pressure": [ 40.1, 39.9 ] },
@@ -193,8 +178,8 @@ int custom_type_with_exceptions() {
 ])"_padded;
   ondemand::parser parser;
   ondemand::document doc = parser.iterate(json);
-  for (auto val : doc) {
+  for (auto value : doc) {
-    Car c(val);
+    Car c(value);
     std::cout << c.make << std::endl;
   }
   return 0;

tests/ondemand/ondemand_stl_types_tests.cpp

@@ -0,0 +1,257 @@
+#include "simdjson.h"
+#include "test_ondemand.h"
+
+#include <string>
+#include <vector>
+#include <list>
+#include <set>
+#include <stack>
+#include <queue>
+#include <deque>
+#include <unordered_set>
+#include <optional>
+
+#if SIMDJSON_SUPPORTS_DESERIALIZATION
+class Array : public std::vector<float> {};
+static_assert(simdjson::concepts::appendable_containers<Array>, "Array must be appendable_containers");
+static_assert(!simdjson::require_custom_serialization<Array>);
+namespace simdjson {
+// This tag_invoke MUST be inside simdjson namespace
+template <typename simdjson_value>
+auto tag_invoke(deserialize_tag, simdjson_value &val, Array& out) {
+    simdjson::ondemand::array arr;
+    SIMDJSON_TRY(val.get_array().get(arr));
+    for (auto v : arr) {
+      float temp;
+      if (auto const err = v.get<float>().get(temp); err) {
+        return err;
+      }
+      out.push_back(temp);
+      out.push_back(temp); // adding it twice
+    }
+    return error_code::SUCCESS;
+}
+} // namespace simdjson
+
+// require_custom_serialization
+#endif // SIMDJSON_SUPPORTS_DESERIALIZATION
+
+namespace stl_types {
+#if SIMDJSON_EXCEPTIONS && SIMDJSON_SUPPORTS_DESERIALIZATION
+
+bool basic_general_madness() {
+  TEST_START();
+  simdjson::padded_string json =
+      R"( [ { "codes": [1,2,3,4,18,19] },
+            { "codes": [1,3,4,111,1111] } ])"_padded;
+
+  simdjson::ondemand::parser parser;
+  simdjson::ondemand::document doc = parser.iterate(json);
+  std::vector<uint16_t> codes;
+  for (auto val : doc) {
+    simdjson::ondemand::object obj;
+    SIMDJSON_TRY(val.get_object().get(obj));
+    obj["codes"].get(codes); // append to it
+  }
+
+  if (codes.size() != 11) {
+    return false;
+  }
+  if (codes[5] != 19 || codes[7] != 3 || codes[9] != 111) {
+    return false;
+  }
+
+  TEST_SUCCEED();
+}
+
+bool basic_general_madness_vector() {
+  TEST_START();
+  simdjson::padded_string json =
+      R"( [ { "codes": [1.2, 3.4, 5.6, 7.8, 9.0] },
+            { "codes": [2.2, 4.4, 6.6, 8.8, 10.0] } ])"_padded;
+
+  simdjson::ondemand::parser parser;
+  simdjson::ondemand::document doc = parser.iterate(json);
+  std::vector<float> codes;
+  for (auto val : doc) {
+    simdjson::ondemand::object obj;
+    SIMDJSON_TRY(val.get_object().get(obj));
+    obj["codes"].get(codes); // append to it
+  }
+
+  if (codes.size() != 10) {
+    return false;
+  }
+  if (codes[5] != 2.2f || codes[7] != 6.6f || codes[9] != 10.0f) {
+    return false;
+  }
+
+  TEST_SUCCEED();
+}
+
+bool basic_general_madness_list() {
+  TEST_START();
+  simdjson::padded_string json =
+      R"( [ { "codes": [1.2, 3.4, 5.6, 7.8, 9.0] },
+            { "codes": [2.2, 4.4, 6.6, 8.8, 10.0] } ])"_padded;
+
+  simdjson::ondemand::parser parser;
+  simdjson::ondemand::document doc = parser.iterate(json);
+  std::list<float> codes;
+  for (auto val : doc) {
+    simdjson::ondemand::object obj;
+    SIMDJSON_TRY(val.get_object().get(obj));
+    obj["codes"].get(codes); // append to it
+  }
+
+  if (codes.size() != 10) {
+    return false;
+  }
+  if (codes.back() != 10.0f || codes.front() != 1.2f) {
+    return false;
+  }
+
+  TEST_SUCCEED();
+}
+
+
+
+bool basic_general_madness_Array() {
+  TEST_START();
+  simdjson::padded_string json =
+      R"( [ { "codes": [1.2, 3.4, 5.6, 7.8, 9.0] },
+            { "codes": [2.2, 4.4, 6.6, 8.8, 10.0] } ])"_padded;
+
+  simdjson::ondemand::parser parser;
+  simdjson::ondemand::document doc = parser.iterate(json);
+  Array codes;
+  for (auto val : doc) {
+    simdjson::ondemand::object obj;
+    SIMDJSON_TRY(val.get_object().get(obj));
+    obj["codes"].get(codes); // append to it
+  }
+  ASSERT_EQUAL(codes.size(), 20);
+  TEST_SUCCEED();
+}
+
+
+template <template <typename...> typename Container, typename ValT = float>
+bool basic_general_madness_container() {
+  TYPED_TEST_START(Container<ValT>);
+
+  simdjson::padded_string json =
+      R"( [ { "codes": [1.0, 3.4, 5.6, 7.8, 9.0] },
+            { "codes": [2.2, 4.4, 6.6, 8.8, 10.0] } ])"_padded;
+
+  simdjson::ondemand::parser parser;
+  simdjson::ondemand::document doc = parser.iterate(json);
+  Container<ValT> codes;
+  for (auto val : doc) {
+    simdjson::ondemand::object obj;
+    SIMDJSON_TRY(val.get_object().get(obj));
+    obj["codes"].get(codes); // append to it
+  }
+
+  if (codes.size() != 10) {
+    return false;
+  }
+
+
+  if constexpr (requires {codes.front();}) {
+    if constexpr (requires {*codes.front();}) {
+      if (*codes.front() != 1.0) {
+        return false;
+      }
+    } else {
+      if (codes.front() != 1.0) {
+        return false;
+      }
+    }
+  }
+  if constexpr (requires {codes.back();} ) {
+    if constexpr (requires {*codes.back();}) {
+      if (*codes.back() != 10.0) {
+        return false;
+      }
+    } else {
+      if (codes.back() != 10.0) {
+        return false;
+      }
+    }
+  }
+
+  TEST_SUCCEED();
+}
+
+
+#endif // SIMDJSON_EXCEPTIONS
+bool run() {
+  return
+#if SIMDJSON_EXCEPTIONS && SIMDJSON_SUPPORTS_DESERIALIZATION
+      basic_general_madness() &&
+      basic_general_madness_vector() &&
+      basic_general_madness_list() &&
+      basic_general_madness_Array() &&
+      basic_general_madness_container<std::vector>() &&
+      basic_general_madness_container<std::list>() &&
+      basic_general_madness_container<std::set>() &&
+      basic_general_madness_container<std::stack>() &&
+      basic_general_madness_container<std::queue>() &&
+      basic_general_madness_container<std::deque>() &&
+      basic_general_madness_container<std::priority_queue>() &&
+      basic_general_madness_container<std::unordered_set>() &&
+      basic_general_madness_container<std::multiset>() &&
+      basic_general_madness_container<std::unordered_multiset>() &&
+        // double:
+      basic_general_madness_container<std::vector, double>() &&
+      basic_general_madness_container<std::list, double>() &&
+      basic_general_madness_container<std::set, double>() &&
+      basic_general_madness_container<std::stack, double>() &&
+      basic_general_madness_container<std::queue, double>() &&
+      basic_general_madness_container<std::deque, double>() &&
+      basic_general_madness_container<std::priority_queue, double>() &&
+      basic_general_madness_container<std::unordered_set, double>() &&
+      basic_general_madness_container<std::multiset, double>() &&
+      basic_general_madness_container<std::unordered_multiset, double>() &&
+        // unique_ptr<double>:
+      basic_general_madness_container<std::vector, std::unique_ptr<double>>() &&
+      basic_general_madness_container<std::list, std::unique_ptr<double>>() &&
+      basic_general_madness_container<std::set, std::unique_ptr<double>>() &&
+      basic_general_madness_container<std::stack, std::unique_ptr<double>>() &&
+      basic_general_madness_container<std::deque, std::unique_ptr<double>>() &&
+      basic_general_madness_container<std::queue, std::unique_ptr<double>>() &&
+      basic_general_madness_container<std::priority_queue, std::unique_ptr<double>>() &&
+      basic_general_madness_container<std::unordered_set, std::unique_ptr<double>>() &&
+      basic_general_madness_container<std::multiset, std::unique_ptr<double>>() &&
+      basic_general_madness_container<std::unordered_multiset, std::unique_ptr<double>>() &&
+        // shared_ptr<double>:
+      basic_general_madness_container<std::vector, std::shared_ptr<double>>() &&
+      basic_general_madness_container<std::list, std::shared_ptr<double>>() &&
+      basic_general_madness_container<std::set, std::shared_ptr<double>>() &&
+      basic_general_madness_container<std::stack, std::shared_ptr<double>>() &&
+      basic_general_madness_container<std::deque, std::shared_ptr<double>>() &&
+      basic_general_madness_container<std::queue, std::shared_ptr<double>>() &&
+      basic_general_madness_container<std::priority_queue, std::shared_ptr<double>>() &&
+      basic_general_madness_container<std::unordered_set, std::shared_ptr<double>>() &&
+      basic_general_madness_container<std::multiset, std::shared_ptr<double>>() &&
+      basic_general_madness_container<std::unordered_multiset, std::shared_ptr<double>>() &&
+        // optional<double>:
+      basic_general_madness_container<std::vector, std::optional<double>>() &&
+      basic_general_madness_container<std::list, std::optional<double>>() &&
+      basic_general_madness_container<std::set, std::optional<double>>() &&
+      basic_general_madness_container<std::stack, std::optional<double>>() &&
+      basic_general_madness_container<std::deque, std::optional<double>>() &&
+      basic_general_madness_container<std::queue, std::optional<double>>() &&
+      basic_general_madness_container<std::priority_queue, std::optional<double>>() &&
+      basic_general_madness_container<std::unordered_set, std::optional<double>>() &&
+      basic_general_madness_container<std::multiset, std::optional<double>>() &&
+      basic_general_madness_container<std::unordered_multiset, std::optional<double>>() &&
+#endif // SIMDJSON_EXCEPTIONS
+      true;
+}
+
+} // namespace stl_types
+
+int main(int argc, char *argv[]) {
+  return test_main(argc, argv, stl_types::run);
+}

tests/test_macros.h

@@ -110,6 +110,7 @@ simdjson_inline bool assert_iterate_error(T &arr, simdjson::error_code expected,
   return assert_equal( count, 1, operation );
 }
 #define TEST_START()                    do { std::cout << "> Running " << __func__ << " ..." << std::endl; } while(0);
+#define TYPED_TEST_START(T)             do { std::cout << "> Running " << __func__ << "<" << typeid(T).name() << "> ..." << std::endl; } while(0);
 #define SUBTEST(NAME, TEST)             do { std::cout << " - Subtest " << (NAME) << " ..." << std::endl; if (!(TEST)) { return false; } } while (0);
 #define ASSERT_EQUAL(ACTUAL, EXPECTED)  do { if (!::assert_equal  ((ACTUAL), (EXPECTED), #ACTUAL)) { return false; } } while (0);
 #define ASSERT_RESULT(ACTUAL, EXPECTED) do { if (!::assert_result ((ACTUAL), (EXPECTED), #ACTUAL)) { return false; } } while (0);