Merge branch 'develop' into claude/fix-issue-3989-db7e45

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

.github/CONTRIBUTING.md

@@ -111,6 +111,8 @@ context which existing file needs to be extended, and only very few cases requir
 When fixing a bug, edit `unit-regression3.cpp` and add a section referencing the fixed issue.
 `unit-regression2.cpp` holds the older tests; the two files exist because a single one grew large enough for the
 MinGW linker to fail relocating it, so please keep adding to the smaller file rather than growing the larger one.
+Tests that call `sax_parse` go into `unit-sax_parse.cpp` rather than into a large test file: every call instantiates
+the parser and the binary reader that recover from errors, which grows a test file considerably.
 
 #### Exceptions
 

README.md

@@ -495,7 +495,7 @@ bool key(string_t& val);
 bool parse_error(std::size_t position, const std::string& last_token, const detail::exception& ex);
 ```
 
-The return value of each function determines whether parsing should proceed.
+The return value of each function determines whether parsing should proceed. For `parse_error`, returning `true` [recovers from the error](https://json.nlohmann.me/features/parsing/error_recovery/): the parser repairs the input and continues.
 
 To implement your own SAX handler, proceed as follows:
 
@@ -503,7 +503,7 @@ To implement your own SAX handler, proceed as follows:
 2. Create an object of your SAX interface class, e.g. `my_sax`.
 3. Call `bool json::sax_parse(input, &my_sax)`; where the first parameter can be any input like a string or an input stream and the second parameter is a pointer to your SAX interface.
 
-Note the `sax_parse` function only returns a `bool` indicating the result of the last executed SAX event. It does not return a  `json` value - it is up to you to decide what to do with the SAX events. Furthermore, no exceptions are thrown in case of a parse error -- it is up to you what to do with the exception object passed to your `parse_error` implementation. Internally, the SAX interface is used for the DOM parser (class `json_sax_dom_parser`) as well as the acceptor (`json_sax_acceptor`), see file [`json_sax.hpp`](https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/input/json_sax.hpp).
+Note the `sax_parse` function only returns a `bool` indicating whether the input was parsed without errors and no SAX event returned `false`. It does not return a  `json` value - it is up to you to decide what to do with the SAX events. Furthermore, no exceptions are thrown in case of a parse error -- it is up to you what to do with the exception object passed to your `parse_error` implementation. Internally, the SAX interface is used for the DOM parser (class `json_sax_dom_parser`) as well as the acceptor (`json_sax_acceptor`), see file [`json_sax.hpp`](https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/input/json_sax.hpp).
 
 ### STL-like access
 

docs/mkdocs/docs/api/basic_json/sax_parse.md

@@ -104,7 +104,9 @@ The SAX event lister must follow the interface of [`json_sax`](../json_sax/index
 
 ## Return value
 
-return value of the last processed SAX event
+`#!cpp true` if the input was parsed without errors and no SAX event returned `#!cpp false`; `#!cpp false` otherwise.
+In particular, the result is `#!cpp false` for input with errors, even if the SAX parser recovered from all of them
+(see [error recovery](../../features/parsing/error_recovery.md)).
 
 ## Exception safety
 
@@ -161,6 +163,7 @@ use the same file with stdio functions, but it must not wait for another thread
 - Added `ignore_trailing_commas` in version 3.13.0.
 - Added `tag_handler` in version 3.13.0.
 - Extended container support (1) to include types with lvalue-only ADL `begin`/`end` (matching `std::begin`/`std::end` semantics) in version 3.13.0.
+- Recovering from parse errors (see [`parse_error`](../json_sax/parse_error.md)) added in version 3.13.0.
 - Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0.
 - `JSON_PRECISE_STREAM_POSITION` added in version 3.13.0 to optionally leave a `#!cpp std::istream` positioned right
   after the parsed value when `strict` is `#!cpp false`.

docs/mkdocs/docs/api/json_sax/index.md

@@ -7,7 +7,8 @@ struct json_sax;
 
 This class describes the SAX interface used by [sax_parse](../basic_json/sax_parse.md). Each function is called in
 different situations while the input is parsed. The boolean return value informs the parser whether to continue
-processing the input.
+processing the input; for [`parse_error`](parse_error.md), it decides whether to
+[recover from the error](../../features/parsing/error_recovery.md).
 
 For instance, parsing the JSON text `{"a": [1, true]}` triggers the following callbacks, in order:
 

docs/mkdocs/docs/api/json_sax/parse_error.md

@@ -21,11 +21,18 @@ A parse error occurred.
 
 ## Return value
 
-Whether parsing should proceed (**must return `#!cpp false`**).
+Whether to recover from the error:
+
+- `#!cpp false` stops parsing.
+- `#!cpp true` recovers from the error: the error is repaired and parsing continues. If that is not possible, which
+  happens in the binary formats when the end of the item with the error is unknown, the value read so far is completed
+  and parsing stops. See [error recovery](../../features/parsing/error_recovery.md) for how errors are repaired.
+
+Either way, [`sax_parse`](../basic_json/sax_parse.md) returns `#!cpp false`.
 
 ## Examples
 
-??? example
+??? example "Example: (1) the SAX interface"
 
     The example below shows how the SAX interface is used.
 
@@ -39,12 +46,29 @@ Whether parsing should proceed (**must return `#!cpp false`**).
     --8<-- "examples/sax_parse.output"
     ```
 
+??? example "Example: (2) recovering from errors"
+
+    The example below shows how a SAX parser recovers from errors.
+
+    ```cpp
+    --8<-- "examples/sax_parse__error_recovery.cpp"
+    ```
+    
+    Output:
+    
+    ```
+    --8<-- "examples/sax_parse__error_recovery.output"
+    ```
+
 ## See also
 
 - [sax_parse](../basic_json/sax_parse.md) - SAX parser
 - [Parsing and Exceptions](../../features/parsing/parse_exceptions.md) - the article on handling parse errors without
   exceptions
+- [Error Recovery](../../features/parsing/error_recovery.md) - the article on recovering from parse errors
 
 ## Version history
 
 - Added in version 3.2.0.
+- Returning `#!cpp true` recovers from the error since version 3.13.0; before, parsing stopped, but the result of
+  [`sax_parse`](../basic_json/sax_parse.md) could be wrong.

docs/mkdocs/docs/examples/no_exceptions_access.cpp

@@ -1,42 +0,0 @@
-#include <iostream>
-#include <nlohmann/json.hpp>
-
-using json = nlohmann::json;
-
-int main()
-{
-    json j = json::parse(R"({"name": "Mary", "age": 42})");
-
-    // look up the key, then test the type: neither step throws
-    for (const char* key : {"name", "age", "city"})
-    {
-        const auto it = j.find(key);
-        if (it == j.end())
-        {
-            std::cout << key << ": missing\n";
-        }
-        else if (it->is_string())
-        {
-            std::cout << key << ": string \"" << it->get_ref<const std::string&>() << "\"\n";
-        }
-        else
-        {
-            std::cout << key << ": not a string, but " << it->type_name() << '\n';
-        }
-    }
-
-    // get_ptr returns a null pointer if the value has another type
-    const std::string* name = j["name"].get_ptr<const std::string*>();
-    const std::string* age = j["age"].get_ptr<const std::string*>();
-    std::cout << "get_ptr<string*>: name = " << (name != nullptr) << ", age = " << (age != nullptr) << '\n';
-
-    // value() is NOT exception-free: it throws if the key exists with a different type
-    try
-    {
-        std::cout << j.value("name", 0) << '\n';
-    }
-    catch (const json::type_error& e)
-    {
-        std::cout << e.what() << '\n';
-    }
-}

docs/mkdocs/docs/examples/no_exceptions_access.output

@@ -1,5 +0,0 @@
-name: string "Mary"
-age: not a string, but number
-city: missing
-get_ptr<string*>: name = 1, age = 0
-[json.exception.type_error.302] type must be number, but is string

docs/mkdocs/docs/examples/no_exceptions_convert.c++17.cpp

@@ -1,46 +0,0 @@
-#include <iostream>
-#include <optional>
-#include <string>
-#include <nlohmann/json.hpp>
-
-using json = nlohmann::json;
-
-struct person
-{
-    std::string name;
-    int age;
-};
-
-NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(person, name, age)
-
-// Compile this function with exceptions enabled and call it from code that does not use them.
-std::optional<person> to_person(const json& j)
-{
-    try
-    {
-        return j.get<person>();
-    }
-    catch (const json::exception&)
-    {
-        return std::nullopt;
-    }
-}
-
-int main()
-{
-    const json good = {{"name", "Mary"}, {"age", 42}};
-    const json bad = {{"name", "Mary"}, {"age", "forty-two"}};
-    const json incomplete = {{"name", "Mary"}};
-
-    for (const json& j : {good, bad, incomplete})
-    {
-        if (const auto p = to_person(j))
-        {
-            std::cout << "person: " << p->name << ", " << p->age << '\n';
-        }
-        else
-        {
-            std::cout << "not a person: " << j << '\n';
-        }
-    }
-}

docs/mkdocs/docs/examples/no_exceptions_convert.c++17.output

@@ -1,3 +0,0 @@
-person: Mary, 42
-not a person: {"age":"forty-two","name":"Mary"}
-not a person: {"name":"Mary"}

docs/mkdocs/docs/examples/no_exceptions_parse.cpp

@@ -1,28 +0,0 @@
-#include <cstdint>
-#include <iostream>
-#include <vector>
-#include <nlohmann/json.hpp>
-
-using json = nlohmann::json;
-
-// None of the calls below throws, so this example also works with -fno-exceptions.
-int main()
-{
-    const std::string invalid = R"({"name": "Mary", "age": )";
-
-    // parse() with allow_exceptions = false returns a discarded value
-    json j = json::parse(invalid, nullptr, false);
-    std::cout << std::boolalpha << "parse: discarded = " << j.is_discarded() << '\n';
-
-    // accept() only tells whether the input is valid JSON
-    std::cout << "accept: " << json::accept(invalid) << '\n';
-
-    // the binary formats have the same parameter
-    const std::vector<std::uint8_t> truncated_cbor = {0x83, 0x01};
-    json c = json::from_cbor(truncated_cbor, true, false);
-    std::cout << "from_cbor: discarded = " << c.is_discarded() << '\n';
-
-    // valid input is parsed as usual
-    json valid = json::parse(R"({"name": "Mary"})", nullptr, false);
-    std::cout << "valid input: " << valid << '\n';
-}

docs/mkdocs/docs/examples/no_exceptions_parse.output

@@ -1,4 +0,0 @@
-parse: discarded = true
-accept: false
-from_cbor: discarded = true
-valid input: {"name":"Mary"}

docs/mkdocs/docs/examples/parse_error_position.cpp

@@ -1,42 +0,0 @@
-#include <iostream>
-#include <utility>
-#include <nlohmann/json.hpp>
-
-using json = nlohmann::json;
-
-// line and column (both starting at 1) of a byte index in a text
-std::pair<std::size_t, std::size_t> line_column(const std::string& input, std::size_t byte)
-{
-    std::size_t line = 1;
-    std::size_t column = 1;
-    for (std::size_t i = 0; i + 1 < byte && i < input.size(); ++i)
-    {
-        if (input[i] == '\n')
-        {
-            ++line;
-            column = 1;
-        }
-        else
-        {
-            ++column;
-        }
-    }
-    return {line, column};
-}
-
-int main()
-{
-    const std::string input = "{\n  \"a\": 1,\n  \"b\": ]\n}";
-
-    try
-    {
-        const json j = json::parse(input);
-        std::cout << j << '\n';
-    }
-    catch (const json::parse_error& e)
-    {
-        const auto position = line_column(input, e.byte);
-        std::cout << e.what() << '\n';
-        std::cout << "byte " << e.byte << " = line " << position.first << ", column " << position.second << '\n';
-    }
-}

docs/mkdocs/docs/examples/parse_error_position.output

@@ -1,2 +0,0 @@
-[json.exception.parse_error.101] parse error at line 3, column 8: syntax error while parsing value - unexpected ']'; expected '[', '{', or a literal
-byte 20 = line 3, column 8

docs/mkdocs/docs/examples/parse_error_position_diagnostic.cpp

@@ -1,46 +0,0 @@
-#define JSON_DIAGNOSTIC_POSITIONS 1
-#include <iostream>
-#include <utility>
-#include <nlohmann/json.hpp>
-
-using json = nlohmann::json;
-
-// line and column (both starting at 1) of a byte index in a text
-std::pair<std::size_t, std::size_t> line_column(const std::string& input, std::size_t byte)
-{
-    std::size_t line = 1;
-    std::size_t column = 1;
-    for (std::size_t i = 0; i + 1 < byte && i < input.size(); ++i)
-    {
-        if (input[i] == '\n')
-        {
-            ++line;
-            column = 1;
-        }
-        else
-        {
-            ++column;
-        }
-    }
-    return {line, column};
-}
-
-int main()
-{
-    const std::string input = "{\n  \"name\": \"Mary\",\n  \"age\": \"forty-two\"\n}";
-    const json j = json::parse(input); // the input is valid JSON ...
-
-    try
-    {
-        const int age = j["age"]; // ... but the value has the wrong type
-        std::cout << age << '\n';
-    }
-    catch (const json::exception& e)
-    {
-        std::cout << e.what() << '\n';
-
-        // start_pos() is a 0-based index into the input; the helper expects a 1-based byte index
-        const auto position = line_column(input, j["age"].start_pos() + 1);
-        std::cout << "the value starts at line " << position.first << ", column " << position.second << '\n';
-    }
-}

docs/mkdocs/docs/examples/parse_error_position_diagnostic.output

@@ -1,2 +0,0 @@
-[json.exception.type_error.302] (bytes 29-40) type must be number, but is string
-the value starts at line 3, column 10

docs/mkdocs/docs/examples/partial_input_buffering.cpp

@@ -1,46 +0,0 @@
-#include <iostream>
-#include <nlohmann/json.hpp>
-
-using json = nlohmann::json;
-
-std::string buffer;
-
-// call for every chunk; returns true and sets `value` once the buffer holds one complete JSON value
-bool push(const std::string& chunk, json& value)
-{
-    buffer += chunk;
-    try
-    {
-        value = json::parse(buffer);
-        buffer.clear();
-        return true;
-    }
-    catch (const json::parse_error& e)
-    {
-        if (e.byte == buffer.size() + 1)
-        {
-            return false; // the input ends prematurely: wait for more data
-        }
-        throw; // a real syntax error
-    }
-}
-
-int main()
-{
-    json value;
-    for (const std::string chunk : {"{\"na", "me\": \"Ma", "ry\", \"l", "ist\": [1, 2", ", 3]}"})
-    {
-        std::cout << "chunk " << chunk << " -> " << (push(chunk, value) ? "complete" : "incomplete") << '\n';
-    }
-    std::cout << value << '\n';
-
-    // a syntax error in the middle is not mistaken for missing data
-    try
-    {
-        push("[1, ]", value);
-    }
-    catch (const json::parse_error& e)
-    {
-        std::cout << e.what() << '\n';
-    }
-}

docs/mkdocs/docs/examples/partial_input_buffering.output

@@ -1,7 +0,0 @@
-chunk {"na -> incomplete
-chunk me": "Ma -> incomplete
-chunk ry", "l -> incomplete
-chunk ist": [1, 2 -> incomplete
-chunk , 3]} -> complete
-{"list":[1,2,3],"name":"Mary"}
-[json.exception.parse_error.101] parse error at line 1, column 5: syntax error while parsing value - unexpected ']'; expected '[', '{', or a literal

docs/mkdocs/docs/examples/partial_input_cbor.cpp

@@ -1,23 +0,0 @@
-#include <iostream>
-#include <sstream>
-#include <nlohmann/json.hpp>
-
-using json = nlohmann::json;
-
-int main()
-{
-    // a CBOR value followed by other data
-    const std::vector<std::uint8_t> cbor = json::to_cbor(json{1, 2, 3});
-    std::string data(cbor.begin(), cbor.end());
-    data += "TRAILING";
-
-    std::istringstream input(data);
-    json j = json::from_cbor(input, false); // strict = false: stop after the first value
-
-    std::cout << "value: " << j << '\n';
-    std::cout << "bytes used: " << input.tellg() << '\n';
-
-    std::string rest;
-    input >> rest;
-    std::cout << "remaining input: " << rest << '\n';
-}

docs/mkdocs/docs/examples/partial_input_cbor.output

@@ -1,3 +0,0 @@
-value: [1,2,3]
-bytes used: 4
-remaining input: TRAILING

docs/mkdocs/docs/examples/partial_input_concatenated.cpp

@@ -1,18 +0,0 @@
-#include <iostream>
-#include <sstream>
-#include <nlohmann/json.hpp>
-
-using json = nlohmann::json;
-
-int main()
-{
-    std::istringstream input(R"({"a":1} [2,3] 4 "s")");
-
-    // check for the end of the stream before each read, because a read at the end throws
-    json j;
-    while (input >> std::ws && input.peek() != std::char_traits<char>::eof())
-    {
-        input >> j;
-        std::cout << j << '\n';
-    }
-}

docs/mkdocs/docs/examples/partial_input_concatenated.output

@@ -1,4 +0,0 @@
-{"a":1}
-[2,3]
-4
-"s"

docs/mkdocs/docs/examples/partial_input_discard_records.cpp

@@ -1,27 +0,0 @@
-#include <iostream>
-#include <sstream>
-#include <nlohmann/json.hpp>
-
-using json = nlohmann::json;
-
-void handle(const json& record)
-{
-    std::cout << "handling " << record << '\n';
-}
-
-int main()
-{
-    std::istringstream file(R"([{"id": 1}, {"id": 2}, {"id": 3}])");
-
-    json result = json::parse(file, [](int depth, json::parse_event_t event, json & record)
-    {
-        if (depth == 1 && event == json::parse_event_t::object_end)
-        {
-            handle(record);
-            return false; // discard the record
-        }
-        return true;
-    });
-
-    std::cout << "result: " << result << '\n';
-}

docs/mkdocs/docs/examples/partial_input_discard_records.output

@@ -1,4 +0,0 @@
-handling {"id":1}
-handling {"id":2}
-handling {"id":3}
-result: []

docs/mkdocs/docs/examples/partial_input_sax_stop.cpp

@@ -1,81 +0,0 @@
-#include <iostream>
-#include <nlohmann/json.hpp>
-
-using json = nlohmann::json;
-
-struct find_id : nlohmann::json_sax<json>
-{
-    bool next_is_id = false;
-    json::number_unsigned_t id = 0;
-
-    bool key(std::string& name) override
-    {
-        next_is_id = (name == "id");
-        return true;
-    }
-
-    bool number_unsigned(json::number_unsigned_t value) override
-    {
-        if (next_is_id)
-        {
-            id = value;
-            return false; // found: stop parsing
-        }
-        return true;
-    }
-
-    bool null() override
-    {
-        return true;
-    }
-    bool boolean(bool /*val*/) override
-    {
-        return true;
-    }
-    bool number_integer(json::number_integer_t /*val*/) override
-    {
-        return true;
-    }
-    bool number_float(json::number_float_t /*val*/, const std::string& /*s*/) override
-    {
-        return true;
-    }
-    bool string(std::string& /*val*/) override
-    {
-        return true;
-    }
-    bool binary(json::binary_t& /*val*/) override
-    {
-        return true;
-    }
-    bool start_object(std::size_t /*elements*/) override
-    {
-        return true;
-    }
-    bool end_object() override
-    {
-        return true;
-    }
-    bool start_array(std::size_t /*elements*/) override
-    {
-        return true;
-    }
-    bool end_array() override
-    {
-        return true;
-    }
-    bool parse_error(std::size_t /*position*/, const std::string& /*last_token*/, const json::exception& /*ex*/) override
-    {
-        return false;
-    }
-};
-
-int main()
-{
-    find_id handler;
-    const bool completed = json::sax_parse(R"({"x": [1, 2, 3], "id": 42, "rest": [4, 5, 6]})", &handler);
-
-    std::cout << std::boolalpha;
-    std::cout << "parse completed: " << completed << '\n';
-    std::cout << "id: " << handler.id << '\n';
-}

docs/mkdocs/docs/examples/partial_input_sax_stop.output

@@ -1,2 +0,0 @@
-parse completed: false
-id: 42

docs/mkdocs/docs/examples/sax_parse__error_recovery.cpp

@@ -0,0 +1,43 @@
+#include <iostream>
+#include <iomanip>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+// a SAX parser that creates a JSON value like json::parse does, but that
+// recovers from parse errors instead of stopping at the first one
+class recovering_parser : public nlohmann::detail::json_sax_dom_parser<json>
+{
+  public:
+    explicit recovering_parser(json& result)
+        : nlohmann::detail::json_sax_dom_parser<json>(result, false)
+    {}
+
+    bool parse_error(std::size_t position,
+                     const std::string& /*last_token*/,
+                     const json::exception& ex)
+    {
+        std::cout << "byte " << position << ": " << ex.what() << '\n';
+
+        // repair the input and continue
+        return true;
+    }
+};
+
+int main()
+{
+    // JSON text with several mistakes that ends too early
+    const std::string text = R"({
+    "name": "Hello World",
+    "tags": ["a" "b",],
+    "valid": tru,
+    "size": 1.,
+    "nested": {"x": 1)";
+
+    json result;
+    recovering_parser sax(result);
+    const bool valid = json::sax_parse(text, &sax);
+
+    std::cout << "\nvalid JSON: " << std::boolalpha << valid << '\n'
+              << std::setw(4) << result << std::endl;
+}

docs/mkdocs/docs/examples/sax_parse__error_recovery.output

@@ -0,0 +1,19 @@
+byte 49: [json.exception.parse_error.101] parse error at line 3, column 20: syntax error while parsing array - unexpected string literal; expected ']'
+byte 51: [json.exception.parse_error.101] parse error at line 3, column 22: syntax error while parsing value - unexpected ']'; expected '[', '{', or a literal
+byte 70: [json.exception.parse_error.101] parse error at line 4, column 17: syntax error while parsing value - invalid literal; last read: '"valid": tru,'
+byte 86: [json.exception.parse_error.101] parse error at line 5, column 15: syntax error while parsing value - invalid number; expected digit after '.'; last read: '1.,'
+byte 109: [json.exception.parse_error.101] parse error at line 6, column 22: syntax error while parsing object - unexpected end of input; expected '}'
+
+valid JSON: false
+{
+    "name": "Hello World",
+    "nested": {
+        "x": 1
+    },
+    "size": 1,
+    "tags": [
+        "a",
+        "b"
+    ],
+    "valid": null
+}

docs/mkdocs/docs/examples/type_recipes_chrono.cpp

@@ -1,56 +0,0 @@
-#include <chrono>
-#include <iostream>
-#include <nlohmann/json.hpp>
-
-using json = nlohmann::json;
-
-namespace nlohmann
-{
-template <typename Rep, typename Period>
-struct adl_serializer<std::chrono::duration<Rep, Period>>
-{
-    static void to_json(json& j, const std::chrono::duration<Rep, Period>& d)
-    {
-        j = d.count();
-    }
-
-    static void from_json(const json& j, std::chrono::duration<Rep, Period>& d)
-    {
-        d = std::chrono::duration<Rep, Period>(j.get<Rep>());
-    }
-};
-
-template <typename Duration>
-struct adl_serializer<std::chrono::time_point<std::chrono::system_clock, Duration>>
-{
-    static void to_json(json& j, const std::chrono::time_point<std::chrono::system_clock, Duration>& t)
-    {
-        j = t.time_since_epoch();
-    }
-
-    static void from_json(const json& j, std::chrono::time_point<std::chrono::system_clock, Duration>& t)
-    {
-        t = std::chrono::time_point<std::chrono::system_clock, Duration>(j.get<Duration>());
-    }
-};
-} // namespace nlohmann
-
-int main()
-{
-    using namespace std::chrono;
-
-    std::cout << std::boolalpha;
-
-    // the unit is not part of the JSON value
-    const json timeout = milliseconds(1500);
-    std::cout << "duration: " << timeout << '\n';
-    std::cout << "as milliseconds: " << timeout.get<milliseconds>().count() << '\n';
-
-    // a system_clock time point is the time since the Unix epoch
-    const time_point<system_clock, milliseconds> t(milliseconds(1700000000123));
-    const json stamp = t;
-    std::cout << "time point: " << stamp << '\n';
-
-    const auto back = stamp.get<time_point<system_clock, milliseconds>>();
-    std::cout << "round trip: " << (back == t) << '\n';
-}

docs/mkdocs/docs/examples/type_recipes_chrono.output

@@ -1,4 +0,0 @@
-duration: 1500
-as milliseconds: 1500
-time point: 1700000000123
-round trip: true

docs/mkdocs/docs/examples/type_recipes_class_hierarchy.c++14.cpp

@@ -1,99 +0,0 @@
-#include <iostream>
-#include <memory>
-#include <stdexcept>
-#include <vector>
-#include <nlohmann/json.hpp>
-
-using json = nlohmann::json;
-
-struct shape
-{
-    virtual ~shape() = default;
-    virtual json serialize() const = 0;
-};
-
-struct circle : shape
-{
-    double radius;
-
-    explicit circle(double r) : radius(r) {}
-
-    json serialize() const override
-    {
-        return {{"type", "circle"}, {"radius", radius}};
-    }
-};
-
-struct rectangle : shape
-{
-    double width;
-    double height;
-
-    rectangle(double w, double h) : width(w), height(h) {}
-
-    json serialize() const override
-    {
-        return {{"type", "rectangle"}, {"width", width}, {"height", height}};
-    }
-};
-
-namespace nlohmann
-{
-template <>
-struct adl_serializer<std::unique_ptr<shape>>
-{
-    static void to_json(json& j, const std::unique_ptr<shape>& p)
-    {
-        j = p ? p->serialize() : json(nullptr);
-    }
-
-    static void from_json(const json& j, std::unique_ptr<shape>& p)
-    {
-        if (j.is_null())
-        {
-            p.reset();
-            return;
-        }
-
-        const auto& type = j.at("type").get_ref<const std::string&>();
-        if (type == "circle")
-        {
-            p = std::make_unique<circle>(j.at("radius").get<double>());
-        }
-        else if (type == "rectangle")
-        {
-            p = std::make_unique<rectangle>(j.at("width").get<double>(), j.at("height").get<double>());
-        }
-        else
-        {
-            throw std::invalid_argument("unknown shape type: " + type);
-        }
-    }
-};
-} // namespace nlohmann
-
-int main()
-{
-    std::vector<std::unique_ptr<shape>> shapes;
-    shapes.push_back(std::make_unique<circle>(1.5));
-    shapes.push_back(std::make_unique<rectangle>(2, 3));
-
-    const json j = shapes;
-    std::cout << j << '\n';
-
-    // reading creates objects of the derived types
-    const auto back = j.get<std::vector<std::unique_ptr<shape>>>();
-    std::cout << std::boolalpha;
-    std::cout << "first is a circle: " << (dynamic_cast<circle*>(back[0].get()) != nullptr) << '\n';
-    std::cout << "second is a rectangle: " << (dynamic_cast<rectangle*>(back[1].get()) != nullptr) << '\n';
-
-    // an unknown type tag is reported
-    try
-    {
-        json{{"type", "star"}}.get<std::unique_ptr<shape>>();
-    }
-    catch (const std::invalid_argument& e)
-    {
-        std::cout << e.what() << '\n';
-    }
-}

docs/mkdocs/docs/examples/type_recipes_class_hierarchy.c++14.output

@@ -1,4 +0,0 @@
-[{"radius":1.5,"type":"circle"},{"height":3.0,"type":"rectangle","width":2.0}]
-first is a circle: true
-second is a rectangle: true
-unknown shape type: star

docs/mkdocs/docs/examples/type_recipes_smart_pointers.c++14.cpp

@@ -1,90 +0,0 @@
-#include <iostream>
-#include <memory>
-#include <vector>
-#include <nlohmann/json.hpp>
-
-using json = nlohmann::json;
-
-namespace nlohmann
-{
-template <typename T>
-struct adl_serializer<std::shared_ptr<T>>
-{
-    static void to_json(json& j, const std::shared_ptr<T>& p)
-    {
-        if (p)
-        {
-            j = *p;
-        }
-        else
-        {
-            j = nullptr;
-        }
-    }
-
-    static void from_json(const json& j, std::shared_ptr<T>& p)
-    {
-        if (j.is_null())
-        {
-            p = nullptr;
-        }
-        else
-        {
-            p = std::make_shared<T>(j.get<typename std::remove_const<T>::type>());
-        }
-    }
-};
-
-template <typename T>
-struct adl_serializer<std::unique_ptr<T>>
-{
-    static void to_json(json& j, const std::unique_ptr<T>& p)
-    {
-        if (p)
-        {
-            j = *p;
-        }
-        else
-        {
-            j = nullptr;
-        }
-    }
-
-    static void from_json(const json& j, std::unique_ptr<T>& p)
-    {
-        if (j.is_null())
-        {
-            p = nullptr;
-        }
-        else
-        {
-            p = std::make_unique<T>(j.get<T>());
-        }
-    }
-};
-} // namespace nlohmann
-
-struct point
-{
-    int x;
-    int y;
-};
-
-NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(point, x, y)
-
-int main()
-{
-    // an empty pointer is written as null
-    const std::vector<std::shared_ptr<point>> points = {std::make_shared<point>(point{1, 2}), nullptr};
-    const json j = points;
-    std::cout << j << '\n';
-
-    // reading allocates new objects
-    const auto back = j.get<std::vector<std::shared_ptr<point>>>();
-    std::cout << back[0]->x << ", " << back[0]->y << ", " << (back[1] == nullptr) << '\n';
-
-    // pointers to const and unique_ptr work as well
-    const auto const_ptr = j[0].get<std::shared_ptr<const point>>();
-    const auto unique = j[0].get<std::unique_ptr<point>>();
-    std::cout << const_ptr->y << ", " << unique->x << '\n';
-}

docs/mkdocs/docs/examples/type_recipes_smart_pointers.c++14.output

@@ -1,3 +0,0 @@
-[{"x":1,"y":2},null]
-1, 2, 1
-2, 1

docs/mkdocs/docs/examples/type_recipes_variant.c++17.cpp

@@ -1,63 +0,0 @@
-#include <iostream>
-#include <stdexcept>
-#include <variant>
-#include <vector>
-#include <nlohmann/json.hpp>
-
-using json = nlohmann::json;
-
-namespace geo
-{
-struct circ
-{
-    double radius;
-};
-
-struct rect
-{
-    double width;
-    double height;
-};
-
-NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(circ, radius)
-NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(rect, width, height)
-
-using figure = std::variant<circ, rect>;
-
-void to_json(json& j, const figure& f)
-{
-    std::visit([&j](const auto & alternative)
-    {
-        j = alternative;
-    }, f);
-    j["type"] = std::holds_alternative<circ>(f) ? "circ" : "rect";
-}
-
-void from_json(const json& j, figure& f)
-{
-    const auto& type = j.at("type").get_ref<const std::string&>();
-    if (type == "circ")
-    {
-        f = j.get<circ>();
-    }
-    else if (type == "rect")
-    {
-        f = j.get<rect>();
-    }
-    else
-    {
-        throw std::invalid_argument("unknown figure type: " + type);
-    }
-}
-} // namespace geo
-
-int main()
-{
-    const std::vector<geo::figure> figures = {geo::circ{2}, geo::rect{3, 4}};
-
-    const json j = figures;
-    std::cout << j << '\n';
-
-    const auto back = j.get<std::vector<geo::figure>>();
-    std::cout << "alternatives read back: " << back[0].index() << ", " << back[1].index() << '\n';
-}

docs/mkdocs/docs/examples/type_recipes_variant.c++17.output

@@ -1,2 +0,0 @@
-[{"radius":2.0,"type":"circ"},{"height":4.0,"type":"rect","width":3.0}]
-alternatives read back: 0, 1

docs/mkdocs/docs/features/arbitrary_types.md

@@ -409,32 +409,6 @@ namespace nlohmann {
 }
 ```
 
-## Why isn't my `to_json` or `from_json` found?
-
-The library calls `to_json` and `from_json` without qualification, so the compiler finds them by
-[argument-dependent lookup](https://en.cppreference.com/w/cpp/language/adl) in the namespace of the type, or in the
-namespaces of its template arguments. The usual reasons for a function that is "not found" are:
-
-- **The type is an alias of a standard type.** After `#!cpp using Hash = std::array<std::uint8_t, 6>;` the type
-  *is* `std::array<std::uint8_t, 6>`, which lives in namespace `std`. A `to_json(json&, const Hash&)` in your namespace
-  is never selected. Either give the type its own identity, for example `#!cpp struct Hash : std::array<std::uint8_t, 6> {};`
-  (the function is then found in `Hash`'s namespace), or specialize
-  [`adl_serializer<Hash>`](#how-do-i-convert-third-party-types).
-- **The function is in the wrong namespace.** It must be in the namespace of the type (a global type needs a global
-  function), not in the namespace of the code that calls the conversion. Specializations of `adl_serializer` belong in
-  namespace `nlohmann`.
-- **It is declared too late.** A conversion can only use what has been declared when it is instantiated. If
-  `#!cpp json j = std::vector<third_party::string>{...};` appears before the `adl_serializer` specialization, the
-  compiler reports an error such as "explicit specialization of `adl_serializer<...>` after instantiation". Put the
-  specialization in a small header that every file includes **before** it uses the type with `json`.
-- **It is a template.** For `template <class T> struct box`, write `template <class T> void to_json(json&, const box<T>&)`,
-  not an overload for one `T`.
-- **It worked by accident.** Some versions found `to_json` overloads in `nlohmann::detail` through argument-dependent
-  lookup of the base class of `basic_json`. Do not rely on this; it is not part of the interface.
-
-For smart pointers, class hierarchies, `std::variant`, and `std::chrono`, see
-[Recipes for common types](type_recipes.md).
-
 ## Why can't I convert to/from `std::any`?
 
 `std::any` is intentionally excluded from `get<T>()`/generic conversion support, so `get<std::any>()` and
@@ -531,7 +505,6 @@ struct bad_serializer
 
 ## See also
 
-- [Recipes for common types](type_recipes.md) - smart pointers, class hierarchies, `std::variant`, and `std::chrono`
 - [Converting values](conversions.md) - the general overview of `get`/`get_to` and implicit conversions
 - [Specializing enum conversion](enum_conversion.md) - map enums to JSON strings instead of integers
 - [Supported macros](macros.md) - reference for `NLOHMANN_DEFINE_TYPE_*` and related macros

docs/mkdocs/docs/features/assertions.md

@@ -7,9 +7,7 @@ detect bugs in client code.
 ## Switch off runtime assertions
 
 Runtime assertions can be switched off by defining the preprocessor macro `NDEBUG` (see the
-[documentation of assert](https://en.cppreference.com/w/cpp/error/assert)) which is the default for release builds. Without `NDEBUG`, the assertions are compiled in and contain the name of the source
-file (`__FILE__`); see [notes for builds and distribution](../integration/index.md#notes-for-builds-and-distribution)
-if that path must not end up in your binaries.
+[documentation of assert](https://en.cppreference.com/w/cpp/error/assert)) which is the default for release builds.
 
 ## Change assertion behavior
 

docs/mkdocs/docs/features/conversions.md

@@ -124,29 +124,6 @@ Implicit conversions are convenient but can be surprising (for example, in overl
 be disabled by defining [`JSON_USE_IMPLICIT_CONVERSIONS`](../api/macros/json_use_implicit_conversions.md) to `#!cpp 0`,
 which forces the explicit `get` form and can catch unintended conversions at compile time.
 
-!!! warning "`auto` copies the JSON value; it does not convert it"
-
-    The type of `#!cpp j["name"]` is `json`, not the C++ type of the value inside. `#!cpp auto` therefore deduces
-    `json`:
-
-    ```cpp
-    json j = {{"name", "Mary"}, {"age", 42}};
-
-    auto name = j["name"];                       // json: a copy of the value; prints as "Mary" (with quotes)
-    std::string s1 = j["name"];                  // std::string: implicit conversion
-    auto s2 = j["name"].get<std::string>();      // std::string: explicit conversion
-    auto& age = j["age"];                        // json&: a reference, no copy
-    age = 43;                                    // changes j
-    ```
-
-    This is also why `#!cpp std::cout << j["name"]` prints the quotes (see
-    [getting a string without quotes](#getting-values-out)), and why a `json` value cannot be passed to `printf`: the
-    argument is not an `int` or a `char*`, and a compiler either rejects passing it through `...` (Clang does) or
-    compiles it and prints garbage. Convert first: `#!cpp std::printf("%d", j["age"].get<int>());`.
-
-    Prefer `get<T>()` over `auto` when you want the C++ value, and `auto&` or `const auto&` when you want to avoid a
-    copy of a large value.
-
 !!! warning "Conversions do not range-check numbers"
 
     Just like C++ itself, the `get` family performs numeric conversions without range checks — retrieving a

docs/mkdocs/docs/features/creating_values.md

@@ -61,25 +61,6 @@ with a string as the first element is treated as an object, everything else as a
     [FAQ](../home/faq.md#brace-initialization-yields-arrays) for details and the opt-in
     [`JSON_BRACE_INIT_COPY_SEMANTICS`](../api/macros/json_brace_init_copy_semantics.md) macro.
 
-### What does this produce?
-
-The following table shows how some common spellings are interpreted. When in doubt, use `#!cpp json::array()`,
-`#!cpp json::object()`, or the `#!cpp json(value)` form with parentheses.
-
-| code                                            | result                       | note                                         |
-|-------------------------------------------------|------------------------------|----------------------------------------------|
-| `#!cpp json j = {};` / `#!cpp json j{};`        | `#!json null`                | use `json::object()` or `json::array()`      |
-| `#!cpp json j = json::object();`                | `#!json {}`                  |                                              |
-| `#!cpp json j = json::array();`                 | `#!json []`                  |                                              |
-| `#!cpp json j(true);`                           | `#!json true`                | parentheses create the value itself          |
-| `#!cpp json j = {true};`                        | `#!json [true]`              | braces create a one-element array (`#!cpp json j{true};` depends on the compiler, see the [FAQ](../home/faq.md#brace-initialization-yields-arrays)) |
-| `#!cpp json j = {{"a", 1}};`                    | `#!json {"a":1}`             | all elements are `[string, value]` pairs: object |
-| `#!cpp json j = {{"a", 1}, {"b"}};`             | `#!json [["a",1],["b"]]`     | one element is not a pair: array             |
-| `#!cpp json j = {{"a", 1}, 2};`                 | `#!json [["a",1],2]`         | a plain value among pairs: array             |
-| `#!cpp json j = {{"a", 1, 2}};`                 | `#!json [["a",1,2]]`         | a three-element list is not a pair: array    |
-| `#!cpp json j = "{\"a\":1}";`                   | `#!json "{\"a\":1}"`           | a string **value**; it is not parsed         |
-| `#!cpp json j = json::parse("{\"a\":1}");`      | `#!json {"a":1}`             | parse text with `parse` or `_json`           |
-
 ## Building incrementally
 
 A value can also be built up piece by piece. Accessing a non-existing object key or array index with

docs/mkdocs/docs/features/element_access/index.md

@@ -22,45 +22,6 @@ flowchart TD
     F -->|"yes"| G["contains() / find()"]
 ```
 
-## Does this key exist?
-
-Use [`contains`](../../api/basic_json/contains.md) to test for a key; it does not modify the value and does not throw:
-
-```cpp
-json j = {{"name", "Mary"}, {"address", {{"city", "Berlin"}}}};
-
-j.contains("name");                   // true
-j.contains("age");                    // false
-j.contains("city");                   // false: contains() only looks at the top level
-j["address"].contains("city");        // true
-j.contains(json::json_pointer("/address/city"));  // true: a JSON pointer tests a nested path in one call
-```
-
-If the value is needed afterwards, [`find`](../../api/basic_json/find.md) tests and accesses with a single lookup:
-
-```cpp
-if (auto it = j.find("name"); it != j.end())
-{
-    std::cout << *it << '\n';
-}
-```
-
-`contains` also returns `true` for a key whose value is `null`; use `j.contains("k") && !j["k"].is_null()` if a
-`null` should count as missing. To read a value with a fallback instead, see [`value`](default_value.md).
-
-!!! warning "`operator[]` inserts missing keys"
-
-    Like `#!cpp std::map::operator[]`, the non-const [`operator[]`](unchecked_access.md) adds a `null` value if the key
-    is missing. Testing a key with it therefore *changes the object*:
-
-    ```cpp
-    json j = {{"foo", 1}};
-    bool absent = j["bar"].is_null();   // true, but j is now {"bar": null, "foo": 1}
-    ```
-
-    Use `contains`/`find` to test, and [`at`](checked_access.md) to access a value that must exist (it throws an
-    [`out_of_range`](../../home/exceptions.md#out-of-range) exception otherwise).
-
 ## See also
 
 - [**operator[]**](../../api/basic_json/operator%5B%5D.md) - unchecked access

docs/mkdocs/docs/features/no_exceptions.md

@@ -1,113 +0,0 @@
-# Working Without Exceptions
-
-By default, the library reports errors by throwing exceptions (see [Exceptions](../home/exceptions.md)). This page
-collects what to use when exceptions are unwanted or unavailable, for example in embedded systems, game engines, or
-code compiled with `-fno-exceptions`.
-
-## Two different questions
-
-1. **Can my code avoid *catching* exceptions?** Yes. For parsing and for accessing values there are functions that
-   report failure through a return value. They work in a normal build and need no `#!cpp try`/`#!cpp catch`.
-2. **Can the library be *compiled* without exceptions?** Yes, with `-fno-exceptions` or by defining
-   [`JSON_NOEXCEPTION`](../api/macros/json_noexception.md). Both have the same effect: every `#!cpp throw` in the
-   library becomes a call to `std::abort()`. The functions listed below never reach a `#!cpp throw` for the failures
-   they report, so they keep working in this configuration. Anything else that fails aborts the program.
-
-## Parsing
-
-| function                                                                                    | on invalid input                                    |
-|---------------------------------------------------------------------------------------------|-----------------------------------------------------|
-| `#!cpp json::parse(input, nullptr, false)`                                                  | returns a *discarded* value; test with `is_discarded()` |
-| [`accept`](../api/basic_json/accept.md)                                                     | returns `#!cpp false`                               |
-| `#!cpp json::from_cbor(input, true, false)` (and the other `from_*` functions)              | returns a *discarded* value                         |
-| [`sax_parse`](../api/basic_json/sax_parse.md) with your own handler                         | returns `#!cpp false` after calling `parse_error`   |
-
-??? example "Example: parse and validate without exceptions"
-
-    ```cpp
-    --8<-- "examples/no_exceptions_parse.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/no_exceptions_parse.output"
-    ```
-
-None of the calls in this example throws, so it also compiles and runs with `-fno-exceptions`.
-
-The discarded value carries no message. If you need the position or the reason, use the SAX interface; see
-[Parsing and exceptions](parsing/parse_exceptions.md).
-
-## Accessing values
-
-The access functions are not equally safe. Only some of them never throw:
-
-| expression                          | if the key is missing or the type is wrong                                    |
-|-------------------------------------|-------------------------------------------------------------------------------|
-| `#!cpp j.contains("k")`             | returns `#!cpp false` for a missing key; never throws                         |
-| `#!cpp j.find("k")`                 | returns `end()` for a missing key; never throws                               |
-| `#!cpp j.is_string()`, ...          | the `is_*` functions test the type; never throw                               |
-| `#!cpp j.get_ptr<const std::string*>()` | returns `#!cpp nullptr` for a different type; never throws                |
-| `#!cpp j.at("k")`                   | throws `out_of_range.403` for a missing key                                   |
-| `#!cpp j.get<int>()`                | throws `type_error.302` for a value that is not a number                      |
-| `#!cpp j.value("k", 0)`             | returns the default for a missing key, but **throws `type_error.302` if `k` exists with another type** |
-| `#!cpp j["k"]` (non-const)          | inserts `null` for a missing key                                              |
-| `#!cpp j["k"]` (const)              | undefined behavior for a missing key                                          |
-
-So reading a value that may be absent or of the wrong type without exceptions takes two steps: look up, then test the
-type.
-
-??? example "Example: look up a key and test its type"
-
-    ```cpp
-    --8<-- "examples/no_exceptions_access.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/no_exceptions_access.output"
-    ```
-
-The last lines of the example show why `value` is not on the safe list: it returns the default only for a *missing*
-key.
-
-For numbers, test with `is_number()` (or `is_number_integer()`, `is_number_unsigned()`, `is_number_float()`) before
-calling `get<int>()`, and see [number handling](types/number_handling.md) for range and precision. Whether a value
-fits into the target type is not checked by `get`.
-
-## Converting to your own types
-
-`from_json` functions (including the ones generated by the
-[`NLOHMANN_DEFINE_TYPE_*` macros](arbitrary_types.md#simplify-your-life-with-macros)) report problems by throwing.
-There is no variant that returns an error code. Without exceptions you have two options:
-
-- Validate the JSON value yourself, as shown above, and fill your struct field by field.
-- Convert in a function that is compiled **with** exceptions enabled and catches them at the boundary, returning
-  `std::optional` or an error code to the rest of your code:
-
-??? example "Example: convert to a struct and report failure as std::optional"
-
-    ```cpp
-    --8<-- "examples/no_exceptions_convert.c++17.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/no_exceptions_convert.c++17.output"
-    ```
-
-## Overriding what happens instead of an exception
-
-With exceptions off, you can replace the `abort()` by your own code, for example to log the message first. See
-[Switch off exceptions](../home/exceptions.md#switch-off-exceptions) and
-[`JSON_THROW_USER`](../api/macros/json_throw_user.md). The handler must not return normally.
-
-## See also
-
-- [Exceptions](../home/exceptions.md) - all exceptions and their ids
-- [Parsing and exceptions](parsing/parse_exceptions.md) - the parsing alternatives in detail
-- [Parsing untrusted input](parsing/untrusted_input.md)
-- [`JSON_NOEXCEPTION`](../api/macros/json_noexception.md)

docs/mkdocs/docs/features/parsing/error_recovery.md

@@ -0,0 +1,122 @@
+# Error Recovery
+
+By default, parsing stops at the first error. With the [SAX interface](sax_interface.md), you can instead ask the
+parser to *recover*: to repair the error and continue, so that you get as much as possible out of malformed input, for
+instance a file that was cut off, JSON edited by hand, or the output of a language model.
+
+## Recovering from errors
+
+The SAX parser's [`parse_error`](../../api/json_sax/parse_error.md) function is called for every error. Its return value
+decides what happens next:
+
+- `#!cpp false` stops parsing. This is what the SAX parsers of the library do, so [`parse`](../../api/basic_json/parse.md)
+  and [`accept`](../../api/basic_json/accept.md) never recover.
+- `#!cpp true` repairs the error and continues parsing.
+
+When recovering, the SAX parser still receives well-formed events: every `start_object` or `start_array` is followed by
+the matching `end_object` or `end_array`, and every `key` is followed by exactly one value. A SAX parser that creates a
+JSON value, such as the one in the example below, therefore gets a complete value. Parsing always ends, and
+[`sax_parse`](../../api/basic_json/sax_parse.md) returns `#!cpp false` for input that is not valid JSON, even if every
+error was repaired. Each token is reported at most once, and the SAX parser can stop at any error by returning
+`#!cpp false`.
+
+!!! example
+
+    The example below derives a SAX parser from the library's parser for `json` values (`json_sax_dom_parser`),
+    and recovers from all errors.
+
+    ```cpp
+    --8<-- "examples/sax_parse__error_recovery.cpp"
+    ```
+    
+    Output:
+    
+    ```
+    --8<-- "examples/sax_parse__error_recovery.output"
+    ```
+
+## How errors are repaired
+
+Each error is repaired with the smallest local edit: a missing separator is inserted, a stray token is removed, what can
+be read of a broken string or number is kept, and a value that cannot be read at all becomes `#!json null`.
+
+| Mistake                   | Repair                                                                         | Example                                  | Result                     |
+|---------------------------|--------------------------------------------------------------------------------|------------------------------------------|----------------------------|
+| missing `,` or `:`        | inserted                                                                       | `#!json [1 2]`, `#!json {"a" 1}`         | `[1,2]`, `{"a":1}`         |
+| missing value             | `#!json null` for an object key or between commas in an array                  | `#!json {"a":}`, `#!json [1,,2]`         | `{"a":null}`, `[1,null,2]` |
+| trailing comma            | removed                                                                        | `#!json [1,2,]`                          | `[1,2]`                    |
+| broken string             | invalid escapes and bytes are replaced (see below); a line break ends the string | `#!json ["a\qb"]`                        | `["aqb"]`                  |
+| broken number             | the longest valid beginning is kept                                            | `#!json [1., 2e+]`                       | `[1,2]`                    |
+| unreadable value          | `#!json null`                                                                  | `#!json [1, NaN, tru]`                   | `[1,null,null]`            |
+| number too large          | passed as infinity, together with its text                                     | `#!json [1e999]`                         | infinity (see below)       |
+| stray `:`                 | removed                                                                        | `#!json ["a":1]`                         | `["a",1]`                  |
+| member without a key      | skipped up to the next `,` or `}`                                              | `#!json {1:2, "b":3}`                    | `{"b":3}`                  |
+| wrong closing bracket     | closes the innermost array or object                                           | `#!json {"a":[1,2}, "b":3}`              | `{"a":[1,2],"b":3}`        |
+| input ends too early      | all open arrays and objects are closed                                         | `#!json {"a":[1,2`                       | `{"a":[1,2]}`              |
+| text before the value     | skipped                                                                        | `#!json )]}'{"a":1}`                     | `{"a":1}`                  |
+
+In a string, an unknown escape like `\q` stands for the escaped character (`q`), as in JavaScript. An invalid `\u`
+escape, a lone surrogate, and ill-formed UTF-8 are each replaced by U+FFFD (REPLACEMENT CHARACTER), and control
+characters are kept. A string without its closing quote ends at the next line break or at the end of the input.
+
+The input after the top-level value is not repaired: as without recovery, it is reported as an error, and parsing stops.
+
+## Binary formats
+
+The binary formats ([BJData](../binary_formats/bjdata.md), [BON8](../binary_formats/bon8.md),
+[BSON](../binary_formats/bson.md), [CBOR](../binary_formats/cbor.md), [MessagePack](../binary_formats/messagepack.md),
+and [UBJSON](../binary_formats/ubjson.md)) have no delimiters to find the next value by. So what can be repaired depends
+on whether the end of the item with the error is known, a distinction that
+[RFC 8949, Section 5.3](https://www.rfc-editor.org/rfc/rfc8949.html#section-5.3) makes for CBOR, too.
+
+If the item is complete, but cannot be passed on as it is, it is replaced, and parsing continues after it:
+
+| Mistake                                                             | Formats                 | Repair                                                                  |
+|---------------------------------------------------------------------|-------------------------|-------------------------------------------------------------------------|
+| tag, if `tag_handler` is `cbor_tag_handler_t::error` (the default)  | CBOR                    | ignored                                                                 |
+| simple value other than `false`, `true`, and `null`, like undefined | CBOR                    | `#!json null`                                                           |
+| number too large for a custom `number_float_t`, like `float`        | all                     | infinity                                                                |
+| character (`C`) that is not ASCII                                   | BJData, UBJSON          | U+FFFD                                                                  |
+| invalid high-precision number (`H`)                                 | BJData, UBJSON          | the longest valid beginning is kept, as for JSON text, or `#!json null` |
+| high-precision number too large                                     | BJData, UBJSON          | passed as infinity, together with its text                              |
+| object key that is not a string                                     | BON8, CBOR, MessagePack | the member is skipped                                                   |
+| element of a type the library does not read, like ObjectId or date  | BSON                    | `#!json null`                                                           |
+| string without its terminator                                       | BSON                    | kept                                                                    |
+| document whose size does not match its content                      | BSON                    | kept                                                                    |
+
+CBOR tags and simple values are repaired as [RFC 8949, Section 6.1](https://www.rfc-editor.org/rfc/rfc8949.html#section-6.1)
+suggests for converting CBOR to JSON. By default, [`sax_parse`](../../api/basic_json/sax_parse.md) reports every tag as
+an error; when recovering, tags are then ignored like with
+[`cbor_tag_handler_t::ignore`](../../api/basic_json/cbor_tag_handler_t.md). Strings that are not valid UTF-8 are no
+error: like [`from_cbor`](../../api/basic_json/from_cbor.md) and the other functions by default, `sax_parse` passes
+them on as they are.
+
+After any other error, the end of the item is unknown: the input ended, a byte is not a valid type marker, or a size
+cannot be right. Parsing then stops, and the value read so far is completed: a key that waits for its value gets
+`#!json null`, and all open arrays and objects are closed. This keeps everything before the error of an input that was
+cut off. The exception is BSON, which stores the size of every document: an element whose end is unknown gets
+`#!json null`, the rest of its document is skipped, and parsing continues after the document.
+
+## Limitations
+
+- A repair is a guess. For example, `#!json {"a" "b": 1}` could be meant as `#!json {"a": "b"}` or as
+  `#!json {"a": null, "b": 1}`; it is repaired to the former. Treat recovered values as a best effort, and check the
+  reported errors.
+- A closing bracket always closes the innermost array or object. If a bracket is missing rather than wrong, the
+  repair differs from the intention: `#!json {"a": {"b": [1, 2}, "c": 3}` is repaired to
+  `#!json {"a": {"b": [1, 2], "c": 3}}`, although `#!json {"a": {"b": [1, 2]}, "c": 3}` may have been meant.
+- Keys without quotes, and strings in single quotes, are not supported; such members are skipped.
+- In the binary formats, a member that is skipped because its key is not a string is lost, and so are the elements of a
+  BSON document after one whose end is unknown.
+- A number that is too large for `number_float_t` is passed as positive or negative infinity. The SAX parser's
+  `number_float` also gets the number's text, but a JSON value cannot store it, and
+  [`dump`](../../api/basic_json/dump.md) serializes infinity as `#!json null`.
+- When parsing is not strict (see [`sax_parse`](../../api/basic_json/sax_parse.md)), a repair may read parts of the
+  input after the value, for instance of the next value in a stream of concatenated values.
+
+## See also
+
+- [SAX interface](sax_interface.md) - implement a custom SAX handler
+- [`parse_error`](../../api/json_sax/parse_error.md) - the SAX event for parse errors
+- [`sax_parse`](../../api/basic_json/sax_parse.md) - generate SAX events
+- [parsing and exceptions](parse_exceptions.md) - control error handling

docs/mkdocs/docs/features/parsing/index.md

@@ -36,9 +36,7 @@ json data = json::parse(f);
 The input must be encoded in UTF-8; other encodings are not supported. The exception is wide-character input, which
 is read as UTF-16 or UTF-32 -- depending on the character type -- and converted to UTF-8; see the
 [`parse`](../../api/basic_json/parse.md) page for an example. A single input may contain only one JSON value.
-Inputs consisting of multiple values separated by newlines are handled by the [JSON Lines](json_lines.md) format; input
-that arrives in chunks or contains several values is covered in
-[Large, streamed, and partial input](large_and_partial_input.md).
+Inputs consisting of multiple values separated by newlines are handled by the [JSON Lines](json_lines.md) format.
 
 By default, the library rejects comments and trailing commas. Both can be enabled with parameters of the `parse`
 function — see [comments](../comments.md) and [trailing commas](../trailing_commas.md).
@@ -94,7 +92,7 @@ again without changing any result.
 
 ## SAX vs. DOM parsing
 
-The library offers two parsing models, and a third, read-only alternative:
+The library offers two parsing models:
 
 - **DOM parsing** (the default): the complete input is read and stored as an in-memory `basic_json` value that can be
   traversed and modified freely. This is what [`parse`](../../api/basic_json/parse.md) does, and it is the right choice
@@ -104,13 +102,6 @@ The library offers two parsing models, and a third, read-only alternative:
   inputs or when you only need to extract parts of the input. See the [SAX interface](sax_interface.md) for details and
   [`sax_parse`](../../api/basic_json/sax_parse.md) for the API.
 
-- **Document and views** (`#!cpp <nlohmann/json_view.hpp>`, added in version 3.13.0): [`json_document::parse`](../../api/basic_json_document/parse.md)
-  reads the same JSON grammar but builds a flat, read-only index of the values instead of a `basic_json` tree. Strings and
-  floating-point numbers are read from the text on demand, and only the parts you
-  [`materialize()`](../../api/basic_json_view/materialize.md) become `basic_json` values. This avoids most of the work when you
-  need only a few values from a large or frequently parsed text; see [Zero-copy JSON views](../json_view.md). It is read-only, so use
-  `parse` when you need to modify the value.
-
 You can influence a DOM parse without switching to the SAX interface by passing a
 [parser callback](parser_callbacks.md), which is called during parsing and can, for example, discard parts of the input.
 
@@ -139,7 +130,7 @@ See [Zero-copy JSON views](../json_view.md) for the concept and the trade-offs.
 When the input is not valid JSON, the `parse` function throws an exception by default. If exceptions are undesired or
 unavailable, the parser can instead return a discarded value, or [`accept`](../../api/basic_json/accept.md) can be used
 to only check whether an input is valid JSON. See [parsing and exceptions](parse_exceptions.md) for the available
-options.
+options. To get as much as possible out of malformed input, a SAX parser can [recover from errors](error_recovery.md).
 
 ## See also
 
@@ -148,10 +139,9 @@ options.
 - [`accept`](../../api/basic_json/accept.md) - check if the input is valid JSON
 - [`sax_parse`](../../api/basic_json/sax_parse.md) - generate SAX events
 - [JSON Lines](json_lines.md) - parse newline-delimited JSON
-- [Large, streamed, and partial input](large_and_partial_input.md) - chunked, concatenated, and very large input
 - [parser callbacks](parser_callbacks.md) - influence the parsing by a callback function
 - [SAX interface](sax_interface.md) - implement a custom SAX handler
-- [Zero-copy JSON views](../json_view.md) - parse into a read-only document and read it through views
 - [parsing and exceptions](parse_exceptions.md) - control error handling
+- [error recovery](error_recovery.md) - get as much as possible out of malformed input
 - [parsing untrusted input](untrusted_input.md) - what to consider when parsing input from untrusted sources
 - [Zero-copy JSON views](../json_view.md) - parse into a document and read it through a view

docs/mkdocs/docs/features/parsing/large_and_partial_input.md

@@ -1,154 +0,0 @@
-# Large, Streamed, and Partial Input
-
-[`parse`](../../api/basic_json/parse.md) reads exactly one complete JSON value and builds it in memory. It cannot be
-paused and resumed, and it does not hand back a half-parsed value when the input ends early. This page shows what to do
-when the input does not fit that model: it arrives in pieces, it contains several values, or it is too large to hold
-as a `json` value.
-
-```mermaid
-flowchart TD
-    A["my input is..."] --> B{"several JSON values in one stream?"}
-    B -->|"yes"| C["read them one at a time"]
-    A --> D{"arriving in chunks (socket, pipe)?"}
-    D -->|"yes"| E["frame the messages, or buffer until complete"]
-    A --> F{"too large to keep in memory?"}
-    F -->|"yes"| G["discard parts with a callback, or use SAX"]
-    A --> H{"only a small part is needed?"}
-    H -->|"yes"| I["stop early with SAX, or read through a view"]
-```
-
-## Several values in one stream
-
-For newline-delimited input, read line by line and parse each line, as described in [JSON Lines](json_lines.md). For
-values that are simply concatenated, [`operator>>`](../../api/operator_gtgt.md) reads one value and leaves the stream
-positioned after it. Check for the end of the stream before each read, because a read at the end throws:
-
-??? example "Example: read concatenated values"
-
-    ```cpp
-    --8<-- "examples/partial_input_concatenated.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/partial_input_concatenated.output"
-    ```
-
-The same works for binary formats. [`from_cbor`](../../api/basic_json/from_cbor.md) and its relatives accept
-`#!cpp strict = false` to stop after the first value and leave the rest of the stream untouched; `tellg()` then reports
-how many bytes the value took:
-
-??? example "Example: read one CBOR value and find out how many bytes it used"
-
-    ```cpp
-    --8<-- "examples/partial_input_cbor.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/partial_input_cbor.output"
-    ```
-
-## Input arriving in chunks
-
-A socket, pipe, or HTTP body hands over data in pieces of arbitrary size, and a piece can end in the middle of a
-number, a string, or an object. The parser does not keep state between calls, so there are two ways to deal with this.
-
-**Frame the messages.** The most robust approach is a protocol that says where a value ends: one value per line
-([JSON Lines](json_lines.md)), a length prefix, or a delimiter. Collect the bytes of one message and parse them when
-the frame is complete. Prefer this whenever you control the protocol.
-
-**Buffer until the value is complete.** If the data has no framing, append every chunk to a buffer and try to parse
-it. A parse error at the very end of the buffer means that the input ended prematurely, while an error anywhere else is
-a real syntax error. The member `byte` of the [`parse_error`](../../home/exceptions.md#jsonexceptionparse_error101)
-exception is one past the buffer size in the first case:
-
-??? example "Example: buffer chunks until the value is complete"
-
-    ```cpp
-    --8<-- "examples/partial_input_buffering.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/partial_input_buffering.output"
-    ```
-
-The example feeds a document in five chunks. The first four are reported as incomplete, and a syntax error is reported as
-such, not as missing data.
-
-!!! warning "Limits of buffering"
-
-    - The buffer must contain exactly one value. Data that belongs to the next value is a syntax error. Use framing if
-      values follow each other without a separator.
-    - A number at the end of the buffer is a complete value, even if more digits are still to come (`12` may be the
-      start of `123`). Buffering cannot detect this; use framing for top-level numbers.
-    - Every attempt parses the buffer from the beginning, so the total work grows quadratically with the size of the
-      value. Limit the size of the buffer for input you do not trust (see [untrusted input](untrusted_input.md)).
-
-## Input too large for memory
-
-The input does not have to become one huge `json` value. The two tools below process it piece by piece.
-
-### Handle and discard elements with a callback
-
-A [parser callback](parser_callbacks.md) is called for every finished value. If it returns `#!cpp false`, the value is
-discarded and its memory is released at once. For a file that consists of one huge array (or one huge object) of
-records, handle each record at depth 1 and discard it:
-
-??? example "Example: handle and discard each record of a large array"
-
-    ```cpp
-    --8<-- "examples/partial_input_discard_records.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/partial_input_discard_records.output"
-    ```
-
-Only one record is in memory at any time. The same recipe, with more detail, is in the
-[parser callbacks](parser_callbacks.md#recipe-streaming-a-large-homogeneous-array) page. To skip entire members you do not
-need, discard them when their key is read; see the [example](parser_callbacks.md) for `parse_event_t::key`.
-
-### Extract a few values and stop with SAX
-
-With the [SAX interface](sax_interface.md), no value is built at all, and **returning `#!cpp false` from any handler
-function stops the parser**. [`sax_parse`](../../api/basic_json/sax_parse.md) then returns `#!cpp false`, and the rest
-of the input is not read. The example finds the first `id` in a document without parsing the remainder:
-
-??? example "Example: stop parsing as soon as a value is found"
-
-    ```cpp
-    --8<-- "examples/partial_input_sax_stop.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/partial_input_sax_stop.output"
-    ```
-
-Note that `sax_parse` returns `#!cpp false` both when a handler stopped the parse and when the input is invalid, so
-record the reason in the handler (here: `id`) if you need to tell the two apart.
-
-### Read parts of a large document with a view
-
-If the whole text is available and you only need to read some of it, a [`json_document`](../json_view.md) from
-`<nlohmann/json_view.hpp>` (added in version 3.13.0) avoids the `basic_json` tree altogether: it keeps the text, builds a flat index of the values,
-and gives read-only [views](../../api/basic_json_view/index.md) of the parts you look at. Only what you
-[`materialize()`](../../api/basic_json_view/materialize.md) becomes a `basic_json` value. See
-[Zero-copy JSON views](../json_view.md) for details and for the lifetime rules.
-
-## See also
-
-- [Parsing](index.md) - overview of the parsing functions
-- [JSON Lines](json_lines.md) - newline-delimited JSON
-- [Parser callbacks](parser_callbacks.md) - discard values while parsing
-- [SAX interface](sax_interface.md) - event-based parsing
-- [Zero-copy JSON views](../json_view.md) - read parts of a large document without building a tree
-- [Untrusted input](untrusted_input.md) - limits for input you do not control

docs/mkdocs/docs/features/parsing/parse_exceptions.md

@@ -21,10 +21,6 @@ catch (json::parse_error& ex)
 In case exceptions are undesired or not supported by the environment, there are different ways to proceed:
 
 
-!!! tip
-
-    [Working without exceptions](../no_exceptions.md) also covers accessing values and converting to your own types.
-
 ## Switch off exceptions
 
 The [`parse()`](../../api/basic_json/parse.md) function accepts a `#!cpp bool` parameter `allow_exceptions` which
@@ -68,7 +64,8 @@ bool parse_error(std::size_t position,
                  const json::exception& ex);
 ```
 
-The return value indicates whether the parsing should continue, so the function should usually return `#!cpp false`.
+The return value decides whether to stop parsing (`#!cpp false`) or to repair the error and continue
+(`#!cpp true`); see [error recovery](error_recovery.md) for the latter.
 
 ??? example "Example: report parse errors without exceptions"
 
@@ -85,61 +82,3 @@ The return value indicates whether the parsing should continue, so the function
     ```
     --8<-- "examples/sax_no_exception.output"
     ```
-
-## Where did the error occur?
-
-The message of a [`parse_error`](../../home/exceptions.md#jsonexceptionparse_error101) for JSON text contains the line
-and column of the error:
-
-```
-[json.exception.parse_error.101] parse error at line 3, column 8: syntax error while parsing value - unexpected ']'; expected '[', '{', or a literal
-```
-
-The exception object itself only stores the **byte index** of the last read character in the member `byte` (the first
-byte of the input has index 1). The same index is passed to `parse_error` in the [SAX interface](sax_interface.md). If
-you need the line and column as numbers, for example to show them in an editor, compute them from the input:
-
-??? example "Example: compute line and column of a parse error"
-
-    ```cpp
-    --8<-- "examples/parse_error_position.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/parse_error_position.output"
-    ```
-
-Columns count bytes, so a line with multi-byte UTF-8 characters before the error may differ from the column your editor
-shows.
-
-### Where is the value that caused a later error?
-
-A `parse_error` is raised while the text is read. Many mistakes show up later: the text is valid JSON, but a value has
-the wrong type when you convert it (`type_error.302`), or a key is missing (`out_of_range.403`). The exception then says
-what is wrong, but not where in the input the value was. Define
-[`JSON_DIAGNOSTIC_POSITIONS`](../../api/macros/json_diagnostic_positions.md) before including the library to add the
-byte range of the offending value to such messages (since version 3.12.0), and to query the range of any value with
-[`start_pos()`](../../api/basic_json/start_pos.md) and [`end_pos()`](../../api/basic_json/end_pos.md):
-
-??? example "Example: locate a value with diagnostic positions"
-
-    ```cpp
-    --8<-- "examples/parse_error_position_diagnostic.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/parse_error_position_diagnostic.output"
-    ```
-
-Positions are only available for values created by [`parse`](../../api/basic_json/parse.md), they are not updated when a
-value is changed, and the macro makes every value 16 bytes larger on 64-bit platforms, so use it where the cost is
-acceptable, for example for configuration files. Note that `start_pos()` is a 0-based index into the input, whereas
-`byte` of a `parse_error` starts at 1.
-
-For binary formats such as CBOR, there are no lines; `byte` is the position in the byte sequence. To find out how many
-bytes a successfully parsed value used, see
-[Several values in one stream](large_and_partial_input.md#several-values-in-one-stream).

docs/mkdocs/docs/features/parsing/sax_interface.md

@@ -60,7 +60,8 @@ bool key(string_t& val);
 bool parse_error(std::size_t position, const std::string& last_token, const json::exception& ex);
 ```
 
-The return value of each function determines whether parsing should proceed.
+The return value of each function determines whether parsing should proceed. For `parse_error`, returning
+`#!cpp true` [recovers from the error](error_recovery.md).
 
 To implement your own SAX handler, proceed as follows:
 
@@ -68,7 +69,7 @@ To implement your own SAX handler, proceed as follows:
 2. Create an object of your SAX interface class, e.g. `my_sax`.
 3. Call `#!cpp bool json::sax_parse(input, &my_sax);` where the first parameter can be any input like a string or an input stream and the second parameter is a pointer to your SAX interface.
 
-Note the `sax_parse` function only returns a `#!cpp bool` indicating the result of the last executed SAX event. It does not return `json` value - it is up to you to decide what to do with the SAX events. Furthermore, no exceptions are thrown in case of a parse error - it is up to you what to do with the exception object passed to your `parse_error` implementation. Internally, the SAX interface is used for the DOM parser (class `json_sax_dom_parser`) as well as the acceptor (`json_sax_acceptor`), see file `json_sax.hpp`.
+Note the `sax_parse` function only returns a `#!cpp bool` indicating whether the input was parsed without errors and no SAX event returned `#!cpp false`. It does not return `json` value - it is up to you to decide what to do with the SAX events. Furthermore, no exceptions are thrown in case of a parse error - it is up to you what to do with the exception object passed to your `parse_error` implementation. Internally, the SAX interface is used for the DOM parser (class `json_sax_dom_parser`) as well as the acceptor (`json_sax_acceptor`), see file `json_sax.hpp`.
 
 ## See also
 

docs/mkdocs/docs/features/parsing/untrusted_input.md

@@ -26,11 +26,9 @@ several alternatives; see [Parsing and exceptions](parse_exceptions.md) for the
   [example](parse_exceptions.md#user-defined-sax-interface) that overrides it to print instead of throw.
 
 If exceptions are unavailable entirely (`-fno-exceptions`, or [`JSON_NOEXCEPTION`](../../api/macros/json_noexception.md)
-defined), every `#!cpp throw` in the library becomes a call to `std::abort()`. The alternatives above do not throw, so
-`parse()` with `allow_exceptions` set to `#!cpp false` (and likewise `accept()` and the `from_*` functions with
-`allow_exceptions` set to `#!cpp false`) can still reject invalid input in that configuration; a plain `parse()` call
-aborts on invalid input. See [Working without exceptions](../no_exceptions.md) and
-[Switch off exceptions](../../home/exceptions.md#switch-off-exceptions) for the details and for overriding the abort with
+defined), every `#!cpp throw` in the library becomes a call to `std::abort()` -- there is no way to recover from a
+parse error of untrusted input in that configuration; see
+[Switch off exceptions](../../home/exceptions.md#switch-off-exceptions) for the details and for overriding this with
 `JSON_THROW_USER`.
 
 ## Nesting depth

docs/mkdocs/docs/features/performance.md

@@ -122,9 +122,7 @@ an adapter, since their template argument order does not match what `basic_json`
   [linear in its size](../api/basic_json/basic_json.md#complexity) for the copy constructor but
   [constant](../api/basic_json/basic_json.md#complexity) for the move constructor. The same applies to assigning a
   large `#!cpp std::string`, `#!cpp std::vector`, or other container into a value: pass it as `#!cpp std::move(x)`
-  rather than `x` whenever `x` is no longer needed afterwards. Since version 3.13.0, converting an rvalue container
-  (`#!cpp json j = std::move(vec);`) moves the elements instead of copying them; the source is then left in a valid but
-  unspecified state.
+  rather than `x` whenever `x` is no longer needed afterwards.
 - **Access without copying.** [`get<T>()`](../api/basic_json/get.md) returns a copy of the stored value converted to
   `T`. When a reference or pointer to the value already stored inside the `basic_json` is enough,
   [`get_ref()`](../api/basic_json/get_ref.md) and [`get_ptr()`](../api/basic_json/get_ptr.md) access it directly:
@@ -153,29 +151,6 @@ an adapter, since their template argument order does not match what `basic_json`
   ["reserving array capacity"](element_access/unchecked_access.md#performance-reserving-array-capacity) for the
   one-line recipe.
 
-## Memory
-
-- **A value is small, its content is on the heap.** A `basic_json` is 16 bytes on a 64-bit platform (a type tag and a
-  union). Strings, arrays, objects, and binary values are allocated on the heap and owned by the value. Destroying the
-  value frees everything it owns.
-- **Copies are deep.** After `#!cpp json b = a;`, changing `b` does not change `a`, and both own their memory. Copying a
-  large value therefore doubles its memory; see [Avoiding copies](#avoiding-copies). `#!cpp auto x = j["key"];` is a
-  copy, `#!cpp auto& x = j["key"];` is not.
-- **A moved-from value is `null`.** After `#!cpp json c = std::move(a);` the value `a` is `#!json null` and owns nothing.
-- **Reading does not require a tree.** If you only read the data, parse it into a [`json_document`](json_view.md)
-  (`#!cpp <nlohmann/json_view.hpp>`, added in version 3.13.0) instead of a `basic_json`. It stores 16 bytes per value, does not copy floating-point
-  numbers or strings without escape sequences out of the text, and creates no `basic_json` value except for the parts
-  you [`materialize()`](../api/basic_json_view/materialize.md). A document that borrows the text needs the text to
-  outlive it; see [Zero-copy JSON views](json_view.md).
-- **Containers keep their capacity.** `clear()` and `erase()` on an array remove the elements, but the underlying
-  `#!cpp std::vector` keeps its allocated capacity, like `#!cpp std::vector::clear` does. To give the memory back,
-  assign a new value (`#!cpp j = json::array();`) or destroy the value.
-- **Freed memory does not always go back to the operating system.** The library returns memory to the allocator
-  (`#!cpp std::allocator` by default, or the [one you configured](types/template_parameters.md)). Whether the process
-  size shrinks then depends on the allocator and the platform, as for any C++ program. A process that parses a large
-  document and drops it is not leaking if its resident size stays high; run it under a tool such as
-  [Valgrind](https://valgrind.org) or the sanitizers to tell a leak from retained memory.
-
 ## Serialization
 
 [`dump()`](../api/basic_json/dump.md) with the default `#!cpp indent = -1` selects "the most compact representation"

docs/mkdocs/docs/features/type_recipes.md

@@ -1,122 +0,0 @@
-# Recipes for Common Types
-
-The library converts the standard containers, strings, numbers, tuples, `std::optional`, and `std::filesystem::path`
-(the last two since version 3.12.0, C++17) out of the box, and your own types once you write conversion functions or use
-the macros (see [Arbitrary type conversions](arbitrary_types.md)). It deliberately does **not** convert smart pointers,
-`std::variant`, `std::chrono` types, or class hierarchies, because there is more than one reasonable JSON
-representation for each of them. This page shows a representation for each that you can copy and adapt.
-
-All recipes use a specialization of [`adl_serializer`](../api/adl_serializer/index.md), which you may provide for types
-you do not own, or free `to_json`/`from_json` functions in the namespace of the type. Place them where they are
-visible before any code that converts the type; see
-[Why isn't my `to_json` found?](arbitrary_types.md#why-isnt-my-to_json-or-from_json-found).
-
-## Smart pointers
-
-A `std::shared_ptr<T>` or `std::unique_ptr<T>` is written as the value it points to, or as `#!json null` for an empty
-pointer, and read back by allocating a new `T`:
-
-??? example "Example: serialize shared_ptr and unique_ptr"
-
-    ```cpp
-    --8<-- "examples/type_recipes_smart_pointers.c++14.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/type_recipes_smart_pointers.c++14.output"
-    ```
-
-With this, containers of smart pointers, pointers to `const`, and members of these types in your own structs convert as
-usual. A pointer to a base class cannot be filled this way, because `T` would have
-to be created as a derived type; see the next section.
-
-Reading creates a new object. Two `shared_ptr`s that pointed to the same object are written twice and read back as two
-separate objects.
-
-## Class hierarchies
-
-!!! tip "Derived classes whose type is known at compile time"
-
-    If you only need to serialize the data members of a derived class, and the code always knows the concrete type, you do
-    not need a type tag. The [`NLOHMANN_DEFINE_DERIVED_TYPE_*` macros](arbitrary_types.md#simplify-your-life-with-macros)
-    (since version 3.12.0) add the members of the derived class to those of its base class. This section is for the case
-    where the concrete type is only known at run time, such as a `std::unique_ptr<shape>` that holds a circle or a
-    rectangle.
-
-JSON has no notion of types, so a value in a hierarchy needs a **type tag** that says which derived class to create.
-Write the tag in the object, and select the class from it when reading:
-
-??? example "Example: serialize a class hierarchy with a type tag"
-
-    ```cpp
-    --8<-- "examples/type_recipes_class_hierarchy.c++14.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/type_recipes_class_hierarchy.c++14.output"
-    ```
-
-A `#!cpp std::vector<std::unique_ptr<shape>>` converts to an array of tagged objects and back, creating a `circle`
-and a `rectangle`. The same works for `std::shared_ptr<shape>`. Remember the virtual destructor: without it, deleting a
-derived object through the base pointer is undefined behavior.
-
-## `std::variant`
-
-A variant has the same problem: the alternative must be recorded. If the alternatives are your own types, write a type
-tag next to their members, exactly as for a hierarchy:
-
-??? example "Example: serialize a std::variant with a type tag"
-
-    ```cpp
-    --8<-- "examples/type_recipes_variant.c++17.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/type_recipes_variant.c++17.output"
-    ```
-
-In the example, the functions are found
-because `geo` is the namespace of the template arguments of `#!cpp std::variant<circ, rect>`; for a variant of only
-standard types (for example `#!cpp std::variant<int, std::string>`) there is no such namespace, and you need an
-`adl_serializer` specialization or a wrapper type of your own.
-
-If the alternatives are JSON-native (numbers, strings, ...), a variant such as `#!cpp std::variant<int, std::string>`
-can instead be written as the plain value, and read by testing the JSON type (`is_number_integer()`, `is_string()`)
-to choose the alternative.
-
-## `std::chrono`
-
-A duration is written as its count and read back with the same representation and period. The **unit is not part of
-the JSON value**, so document it, for example in the member name (`timeout_ms`):
-
-??? example "Example: serialize durations and system_clock time points"
-
-    ```cpp
-    --8<-- "examples/type_recipes_chrono.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/type_recipes_chrono.output"
-    ```
-
-A `system_clock::time_point` with millisecond precision is written as the number of milliseconds since the Unix epoch.
-The time point serializer is limited to `system_clock`,
-because the epoch of other clocks (for example `steady_clock`) has no meaning outside the running program.
-
-If you prefer a text representation such as ISO 8601 (`2023-11-14T22:13:20Z`), write the string with
-`#!cpp std::format("{:%FT%TZ}", t)` and read it with `std::chrono::parse` (both C++20), or with a date library, in the
-same two functions.
-
-## See also
-
-- [Arbitrary type conversions](arbitrary_types.md) - the conversion mechanism and macros
-- [Why isn't my `to_json` found?](arbitrary_types.md#why-isnt-my-to_json-or-from_json-found)
-- [Converting values](conversions.md) - `get`, implicit conversions, and `std::optional`

docs/mkdocs/docs/home/exceptions.md

@@ -39,8 +39,6 @@ classDiagram
 
 Exceptions are used widely within the library. They can, however, be switched off with either using the compiler flag `-fno-exceptions` or by defining the symbol [`JSON_NOEXCEPTION`](../api/macros/json_noexception.md). In this case, exceptions are replaced by `abort()` calls. You can further control this behavior by defining `JSON_THROW_USER` (overriding `#!cpp throw`), `JSON_TRY_USER` (overriding `#!cpp try`), and `JSON_CATCH_USER` (overriding `#!cpp catch`).
 
-See [Working without exceptions](../features/no_exceptions.md) for the functions that report errors without throwing.
-
 Note that [`JSON_THROW_USER`](../api/macros/json_throw_user.md) should leave the current scope (e.g., by throwing or aborting), as continuing after it may yield undefined behavior.
 
 ??? example "Example: switch off exceptions and log errors before aborting"
@@ -195,34 +193,6 @@ This error indicates a syntax error while deserializing a JSON text. The error m
     - Make sure the input is correctly read. Try to write the input to standard output to check if, for instance, the input file was successfully opened.
     - Paste the input to a JSON validator like <https://jsonlint.com> or a tool like [jq](https://jqlang.github.io/jq/).
 
-??? info "Parsing a file fails at line 1, column 1 (or \"unexpected end of input\")"
-
-    The messages `attempting to parse an empty input` (since version 3.11.3) and `unexpected end of input` (also the message of
-    earlier versions for an empty input) at the very start of the input mean
-    that the parser did not see a single character. The library only reads from the stream it is given: it does not
-    open files and cannot tell a missing file from an empty one. The usual causes are:
-
-    - **The file was not opened.** A relative path is resolved against the *working directory of the running program*,
-      not against the source file or the project. IDEs and build tools often start the program in a build directory
-      (for example `build/` or `cmake-build-debug/`), so `"example.json"` may need to be `"../example.json"`. Use an
-      absolute path to rule this out.
-    - **The file is empty**, or a previous run truncated it (for example when it was opened for writing).
-    - **The stream was already read.** A stream whose content has been consumed (by printing it with
-      `std::cout << file.rdbuf()`, or by an earlier `accept`/`parse`/`>>`) is at its end. Parse it once, or rewind it
-      with `seekg(0)` after clearing the state with `clear()`.
-
-    Check the stream before parsing it:
-
-    ```cpp
-    std::ifstream f("example.json");
-    if (!f.is_open())
-    {
-        std::cerr << "cannot open example.json\n";
-        return 1;
-    }
-    json data = json::parse(f);
-    ```
-
 ### json.exception.parse_error.102
 
 JSON uses the `\uxxxx` format to describe Unicode characters. Code points above 0xFFFF are split into two `\uxxxx` entries ("surrogate pairs"). This error indicates that the surrogate pair is incomplete or contains an invalid code point.

docs/mkdocs/docs/home/faq.md

@@ -58,208 +58,6 @@ json j{obj};   // -> {"key":"value"}  (copy, not array)
 
 Without the macro (default behavior), `json j{obj}` creates `[{"key":"value"}]`. This opt-in macro fixes issue #5074 while preserving backwards compatibility for existing code.
 
-## Getting started
-
-### Which file do I need?
-
-!!! question
-
-    Do I have to clone the repository or build the library?
-
-No. The library is header-only: the single file [`json.hpp`](https://github.com/nlohmann/json/releases) from the
-releases page is all you need, including the `_json` literals. Put it in a directory `nlohmann` on your include path.
-Companion headers (`json_fwd.hpp`, `json_view.hpp`, `json_literals.hpp`) are only needed if you use them. See
-[Integration](../integration/index.md#header-only).
-
-### Using CMake or a package manager
-
-!!! question
-
-    How do I add the library with CMake, Conan, vcpkg, Homebrew, or another tool?
-
-See [CMake](../integration/cmake.md) for `find_package`, `add_subdirectory`, and `FetchContent`, and
-[Package managers](../integration/package_managers.md) for the list of supported package managers.
-
-### The IDE cannot open the header
-
-!!! question
-
-    The compiler finds `nlohmann/json.hpp`, but my IDE reports "cannot open source file". Why?
-
-The compiler's include path is set correctly, but the IDE's is not. Add the same directory to the include paths of the
-IDE (or of its language server); the build itself is not affected.
-
-### Compile times
-
-!!! question
-
-    Including the library slows down my build. What can I do?
-
-Include [`json_fwd.hpp`](../integration/compile_times.md#include-json_fwdhpp-in-headers) in headers and `json.hpp` only
-in the source files that need it, instantiate `basic_json` once, and consider precompiled headers or
-[C++20 modules](../features/modules.md). See [Compile times](../integration/compile_times.md).
-
-## Parsing
-
-### Parsing a file fails with "unexpected end of input"
-
-!!! question
-
-    `json::parse(file)` throws `parse_error.101` at line 1, column 1 for a file that is valid JSON. Why?
-
-The parser did not see any character: the file was most likely not opened. A relative path is resolved against the
-working directory of the running program, which is often the build directory of your IDE, not the source directory.
-Check `is_open()` and try an absolute path. Other causes are an empty file and a stream that was already read. See
-[`parse_error.101`](exceptions.md#jsonexceptionparse_error101).
-
-### Input that arrives in chunks
-
-!!! question
-
-    My data comes from a socket in pieces. How do I parse it?
-
-The parser cannot be resumed. Frame the messages (one value per line, a length prefix) and parse each complete frame, or
-buffer the chunks until the value is complete; a `parse_error` at the end of the buffer means the input ended
-prematurely. See [Large, streamed, and partial input](../features/parsing/large_and_partial_input.md#input-arriving-in-chunks).
-
-### Several values in one stream
-
-!!! question
-
-    How do I read concatenated JSON values or one value per line?
-
-Read newline-delimited input line by line ([JSON Lines](../features/parsing/json_lines.md)). For concatenated values, use
-`operator>>` and check for the end of the stream before each read, as shown in
-[Several values in one stream](../features/parsing/large_and_partial_input.md#several-values-in-one-stream).
-
-### Files that are too large for memory
-
-!!! question
-
-    How do I process a huge JSON file?
-
-Handle and discard the records of a large array with a [parser callback](../features/parsing/parser_callbacks.md), stop
-early with the [SAX interface](../features/parsing/sax_interface.md), or read parts of the text through a
-[`json_document`](../features/json_view.md) (added in version 3.13.0). See
-[Input too large for memory](../features/parsing/large_and_partial_input.md#input-too-large-for-memory).
-
-### Position of a parse error
-
-!!! question
-
-    How do I get the line and column of a parse error?
-
-The message contains them. The exception stores the byte index in `byte`, from which you can compute both; see
-[Where did the error occur?](../features/parsing/parse_exceptions.md#where-did-the-error-occur). To locate a value that
-causes a *later* error, such as a `type_error`, use
-[`JSON_DIAGNOSTIC_POSITIONS`](../features/parsing/parse_exceptions.md#where-is-the-value-that-caused-a-later-error).
-
-### Comments and trailing commas
-
-!!! question
-
-    Can the parser read JSON with comments or trailing commas?
-
-Yes, when asked to: see [Comments](../features/comments.md) and [Trailing commas](../features/trailing_commas.md). Both
-are rejected by default.
-
-## Accessing and creating values
-
-### Reading a value into a variable
-
-!!! question
-
-    How do I get a C++ value out of a `json` value?
-
-Use [`get<T>()`](../api/basic_json/get.md), for example `#!cpp int age = j["age"].get<int>();`, or an implicit conversion.
-`#!cpp auto x = j["age"];` is **not** a conversion: it copies the `json` value. See
-[Converting values](../features/conversions.md).
-
-### Strings are printed with quotes
-
-!!! question
-
-    `std::cout << j["name"]` prints `"Mary"` with quotes. How do I get the string?
-
-The value is a `json`, and printing it produces JSON text. Convert it first: `#!cpp j["name"].get<std::string>()`. See
-[Getting a string without quotes](../features/conversions.md#getting-values-out).
-
-### Testing whether a key exists
-
-!!! question
-
-    How do I check if a key exists, without changing the object?
-
-Use `contains` or `find`. Do not test with the non-const `operator[]`: like `std::map::operator[]`, it inserts a `null`
-value for a missing key. See [Does this key exist?](../features/element_access/index.md#does-this-key-exist).
-
-### Reading a value with a fallback
-
-!!! question
-
-    How do I read a value that may be missing?
-
-Use [`value`](../features/element_access/default_value.md), which returns a default for a missing key. It still throws if
-the key exists with a different type; see [Working without exceptions](../features/no_exceptions.md).
-
-### Iterating and nested values
-
-!!! question
-
-    How do I loop over an array or object, or reach a nested value?
-
-See [Iterators](../features/iterators.md) and [`items()`](../api/basic_json/items.md) for loops, and
-[JSON Pointer](../features/json_pointer.md) to address or test a nested value by path.
-
-### Unexpected arrays when creating values
-
-!!! question
-
-    Why does `json j{x}` or `{{"a", 1}, {"b"}}` produce an array instead of what I expected?
-
-Braces create arrays and objects based on their content, and single-element braces create a one-element array. See
-[Brace initialization yields arrays](#brace-initialization-yields-arrays) and the table in
-[Creating values](../features/creating_values.md#what-does-this-produce).
-
-### Keeping the order of object keys
-
-!!! question
-
-    The keys of my object come out sorted. How do I keep the insertion order?
-
-Use `ordered_json`, and call `ordered_json::parse` when reading. See [Object order](../features/object_order.md).
-
-## Converting your own types
-
-### Structs, enums, and optional fields
-
-!!! question
-
-    How do I convert my own types to and from JSON?
-
-Write `to_json`/`from_json` functions or use the `NLOHMANN_DEFINE_TYPE_*` macros; see
-[Arbitrary type conversions](../features/arbitrary_types.md). Enums can be mapped to strings
-([Enum conversion](../features/enum_conversion.md)), and an empty `std::optional` can be omitted
-([Omitting a field](../features/conversions.md#omitting-a-field-when-serializing-stdoptional)).
-
-### Smart pointers, variants, chrono, and class hierarchies
-
-!!! question
-
-    Why can't I convert `std::shared_ptr`, `std::variant`, `std::chrono` types, or a pointer to a base class?
-
-There is more than one sensible JSON representation for them, so the library leaves the choice to you.
-[Recipes for common types](../features/type_recipes.md) shows one for each.
-
-### My `to_json` is not found
-
-!!! question
-
-    I wrote `to_json`/`from_json`, but the compiler does not find them. Why?
-
-Typical causes are a type alias of a standard type, a function in the wrong namespace, or a declaration that comes too
-late. See [Why isn't my `to_json` found?](../features/arbitrary_types.md#why-isnt-my-to_json-or-from_json-found).
-
 ## Limitations
 
 ### Relaxed parsing
@@ -405,36 +203,6 @@ Not directly, but the companion project [json-schema-validator](https://github.c
 builds JSON Schema (draft 7; draft 4 in its older, now-superseded 1.x releases) validation on top of this library
 and is a common recommendation for this use case.
 
-### Memory use
-
-!!! question
-
-    Does the library leak memory? My process stays large after I free a `json` value.
-
-Destroying a value frees everything it owns. Freed memory is returned to the allocator, which does not necessarily give
-it back to the operating system, so a high resident size alone is not a leak. Copies are deep, and `clear()` keeps the
-capacity of an array. See [Memory](../features/performance.md#memory), and use Valgrind or the sanitizers to tell a leak
-from retained memory.
-
-### Reproducible builds
-
-!!! question
-
-    The header path ends up in my binary. How do I get path-independent builds?
-
-The runtime assertions embed `__FILE__`. Define `NDEBUG` (the default for release builds) or map the path prefix; see
-[Notes for builds and distribution](../integration/index.md#notes-for-builds-and-distribution).
-
-### Slow debug builds
-
-!!! question
-
-    Parsing a large file is very slow in my debug build. Can I compile the library with optimizations?
-
-The library is header-only, so there is no separate source file. Keep the code that uses `json` in its own source file and
-compile that file with optimizations; see
-[Notes for builds and distribution](../integration/index.md#notes-for-builds-and-distribution).
-
 ## Exceptions
 
 ### Parsing without exceptions
@@ -443,8 +211,7 @@ compile that file with optimizations; see
 
     Is it possible to indicate a parse error without throwing an exception?
 
-Yes, see [Parsing and exceptions](../features/parsing/parse_exceptions.md) and
-[Working without exceptions](../features/no_exceptions.md).
+Yes, see [Parsing and exceptions](../features/parsing/parse_exceptions.md).
 
 
 ### Key name in exceptions

docs/mkdocs/docs/index.md

@@ -31,10 +31,6 @@ int main()
     j["name"] = "Niels";
     j["list"] = {1, 0, 2};
 
-    // read a value into a C++ variable and use it
-    double pi = j["pi"].get<double>();
-    std::cout << "2 * pi = " << 2 * pi << '\n';
-
     // serialize with an indent of 4 spaces
     std::cout << j.dump(4) << '\n';
 }

docs/mkdocs/docs/integration/index.md

@@ -43,21 +43,6 @@ using json = nlohmann::json;
 to the files you want to process JSON and set the necessary switches to enable C++11 (e.g., `-std=c++11` for GCC and
 Clang).
 
-!!! tip "Which file do I download?"
-
-    For a project without a package manager, the library itself, including the `_json` literals, is **one file**:
-    [`json.hpp`](https://github.com/nlohmann/json/releases/latest/download/json.hpp) from the
-    [releases page](https://github.com/nlohmann/json/releases). You do not need to clone the repository, build
-    anything, or link a library. Put the file in a directory named `nlohmann` that is on your include path (for
-    example `third_party/nlohmann/json.hpp` with `-I third_party`), so that `#include <nlohmann/json.hpp>` works.
-    Download the companion headers listed below only if you use them: `json_view.hpp` for the
-    [zero-copy views](../features/json_view.md), `json_fwd.hpp` for forward declarations, and `json_literals.hpp` if
-    you define `JSON_NO_AUTOMATIC_UDLS`. Keep them in the same `nlohmann` directory.
-
-    Do not copy only parts of the repository's `include/` directory: the headers in it include each other and must be
-    kept together. If your IDE reports "cannot open source file" while the compiler succeeds, the compiler's include
-    path is set correctly but the IDE's is not; add the same directory to the IDE's include paths.
-
 You can further use file
 [`single_include/nlohmann/json_fwd.hpp`](https://github.com/nlohmann/json/blob/develop/single_include/nlohmann/json_fwd.hpp)
 for forward declarations (see [Compile times](compile_times.md)), and file
@@ -70,24 +55,6 @@ types, additionally include
 [`single_include/nlohmann/json_view.hpp`](https://github.com/nlohmann/json/blob/develop/single_include/nlohmann/json_view.hpp);
 see [Zero-copy JSON views](../features/json_view.md).
 
-## Notes for builds and distribution
-
-**Reproducible and path-independent builds.** The runtime assertions use `assert`, which embeds the name of the source
-file (`__FILE__`) in the binary. Release builds do not contain them, because they define `NDEBUG`. If you compile with
-assertions enabled and need binaries that do not depend on the build directory, either define `NDEBUG` or map the
-prefix of the path with the compiler option `-ffile-prefix-map=<old>=<new>` (GCC 8 and later, Clang 10 and later). See
-[Runtime assertions](../features/assertions.md).
-
-**There is no separate source file to compile.** The library is header-only, so there is no `.cpp` that could be
-built with different options than the code that includes it. It is also not available as a precompiled library. To
-compile the library with optimizations in an otherwise unoptimized build (for example to parse large files in a debug
-build, which is slow because of the unoptimized code and the checks of the debug standard library), keep the code that
-uses `json` in a separate source file and set the options for that file only. [Compile times](compile_times.md)
-shows how to [instantiate `basic_json` once](compile_times.md#instantiate-basic_json-once).
-
-**Debugger visualization.** The Natvis file works with the Visual Studio debugger, including the `cppvsdbg` engine in
-Visual Studio Code, but not with debuggers that wrap LLDB, such as `codelldb`; see [Debugging](../home/debugging.md).
-
 ## See also
 
 - [CMake](cmake.md) - integrate the library into a CMake project

docs/mkdocs/mkdocs.yml

@@ -106,7 +106,6 @@ nav:
   - Features:
       - features/index.md
       - features/arbitrary_types.md
-      - features/type_recipes.md
       - Binary Formats:
           - features/binary_formats/index.md
           - features/binary_formats/bjdata.md
@@ -131,13 +130,12 @@ nav:
       - features/modifying_values.md
       - features/modules.md
       - 'nlohmann Namespace': features/namespace.md
-      - features/no_exceptions.md
       - features/object_order.md
       - features/performance.md
       - Parsing:
           - features/parsing/index.md
+          - features/parsing/error_recovery.md
           - features/parsing/json_lines.md
-          - features/parsing/large_and_partial_input.md
           - features/parsing/parse_exceptions.md
           - features/parsing/parser_callbacks.md
           - features/parsing/sax_interface.md

include/nlohmann/detail/input/input_adapters.hpp

@@ -796,17 +796,22 @@ class iterator_input_adapter
         return get_consumed_count() + eof_reads;
     }
 
-    // number of newlines in the consumed range [0, last_index); @a line_start
-    // is set to the index after the last of them (0 if there is none); only
-    // valid when supports_seek
-    std::size_t count_consumed_lines(std::size_t last_index, std::size_t& line_start) const
+    // number of newlines in the consumed range [first_index, last_index); if
+    // there is one, @a line_start is set to the index after the last of them,
+    // otherwise it is left unchanged; only valid when supports_seek
+    std::size_t count_consumed_lines(std::size_t first_index, std::size_t last_index, std::size_t& line_start) const
     {
-        const auto to = std::next(begin, static_cast<typename std::iterator_traits<IteratorType>::difference_type>(last_index));
+        using difference_type = typename std::iterator_traits<IteratorType>::difference_type;
+        const auto from = std::next(begin, static_cast<difference_type>(first_index));
+        const auto to = std::next(from, static_cast<difference_type>(last_index - first_index));
         const auto newline = char_traits<char_type>::to_char_type('\n');
         using reverse_it = std::reverse_iterator<IteratorType>;
-        const auto last_newline = std::find(reverse_it(to), reverse_it(begin), newline);
-        line_start = static_cast<std::size_t>(std::distance(begin, last_newline.base()));
-        return static_cast<std::size_t>(std::count(begin, last_newline.base(), newline));
+        const auto last_newline = std::find(reverse_it(to), reverse_it(from), newline);
+        if (last_newline.base() != from)
+        {
+            line_start = static_cast<std::size_t>(std::distance(begin, last_newline.base()));
+        }
+        return static_cast<std::size_t>(std::count(from, last_newline.base(), newline));
     }
 
     // append the already-consumed characters in the half-open range

include/nlohmann/detail/input/json_sax.hpp

@@ -138,7 +138,9 @@ struct json_sax
     @param[in] position    the position in the input where the error occurs
     @param[in] last_token  the last read token
     @param[in] ex          an exception object describing the error
-    @return whether parsing should proceed (must return false)
+    @return whether to recover from the error: false stops parsing; true
+            repairs the error and continues, or, if that is not possible,
+            stops after completing the value read so far
     */
     virtual bool parse_error(std::size_t position,
                              const std::string& last_token,
@@ -469,12 +471,15 @@ constructor contains the parsed value. Without @a Collect, every value is
 stored in place as it arrives, so after a parse error the value holds what was
 read up to it.
 
-@tparam BasicJsonType  the JSON type
-@tparam Collect  whether to collect the values of containers of unknown size on
-                 a stack (only for a caller that does not use the value after a
-                 parse error)
+@tparam BasicJsonType     the JSON type
+@tparam InputAdapterType  the input adapter of the lexer that can be passed to
+                          the constructor to record diagnostic positions; it
+                          does not matter if no lexer is passed
+@tparam Collect           whether to collect the values of containers of
+                          unknown size on a stack (only for a caller that does
+                          not use the value after a parse error)
 */
-template<typename BasicJsonType, typename InputAdapterType, bool Collect = false>
+template<typename BasicJsonType, typename InputAdapterType = string_input_adapter_type, bool Collect = false>
 class json_sax_dom_parser : public json_sax_dom_error_state
 {
   public:
@@ -772,6 +777,8 @@ class json_sax_dom_parser : public json_sax_dom_error_state
         JSON_HEDLEY_NEVER_INLINE
         void grow()
         {
+            // the stack starts with local_capacity frames and only grows
+            JSON_ASSERT(capacity != 0);
             const std::size_t new_capacity = capacity * 2;
             std::unique_ptr<frame[]> new_heap(new frame[new_capacity]); // NOLINT(cppcoreguidelines-avoid-c-arrays,hicpp-avoid-c-arrays,modernize-avoid-c-arrays)
             std::copy(data, data + count, new_heap.get());
@@ -1581,7 +1588,7 @@ class json_sax_dom_binary_parser : public json_sax_dom_error_state
     lexer_t* m_lexer_ref = nullptr;
 };
 
-template<typename BasicJsonType, typename InputAdapterType>
+template<typename BasicJsonType, typename InputAdapterType = string_input_adapter_type>
 class json_sax_dom_callback_parser : public json_sax_dom_error_state
 {
   public:

include/nlohmann/detail/input/lexer.hpp

@@ -10,7 +10,7 @@
 
 #include <array> // array
 #include <cstddef> // size_t
-#include <cstdint> // uint32_t
+#include <cstdint> // uint8_t, uint32_t
 #include <cstdio> // snprintf
 #include <cstring> // memcmp
 #include <initializer_list> // initializer_list
@@ -381,6 +381,20 @@ class lexer : public lexer_base<BasicJsonType>
         return codepoint;
     }
 
+    /// the code point of the surrogate pair @a high (U+D800..U+DBFF) and @a low (U+DC00..U+DFFF)
+    static constexpr int combine_surrogates(const int high, const int low) noexcept
+    {
+        return static_cast<int>(
+                   // high surrogate occupies the most significant 22 bits
+                   (static_cast<unsigned int>(high) << 10u)
+                   // low surrogate occupies the least significant 15 bits
+                   + static_cast<unsigned int>(low)
+                   // there is still the 0xD800, 0xDC00, and 0x10000 noise
+                   // in the result, so we have to subtract with:
+                   // (0xD800 << 10) + DC00 - 0x10000 = 0x35FDC00
+                   - 0x35FDC00u);
+    }
+
     /*!
     @brief check if the next byte(s) are inside a given range
 
@@ -411,6 +425,7 @@ class lexer : public lexer_base<BasicJsonType>
             else
             {
                 error_message = "invalid string: ill-formed UTF-8 byte";
+                error_cause = error_kind::string_ill_formed_utf8;
                 return false;
             }
         }
@@ -526,6 +541,7 @@ class lexer : public lexer_base<BasicJsonType>
                 case char_traits<char_type>::eof():
                 {
                     error_message = "invalid string: missing closing quote";
+                    error_cause = error_kind::string;
                     return token_type::parse_error;
                 }
 
@@ -582,6 +598,7 @@ class lexer : public lexer_base<BasicJsonType>
                             if (JSON_HEDLEY_UNLIKELY(codepoint1 == -1))
                             {
                                 error_message = "invalid string: '\\u' must be followed by 4 hex digits";
+                                error_cause = error_kind::string_invalid_escape;
                                 return token_type::parse_error;
                             }
 
@@ -589,13 +606,23 @@ class lexer : public lexer_base<BasicJsonType>
                             if (0xD800 <= codepoint1 && codepoint1 <= 0xDBFF)
                             {
                                 // expect next \uxxxx entry
-                                if (JSON_HEDLEY_LIKELY(get() == '\\' && get() == 'u'))
+                                if (JSON_HEDLEY_LIKELY(get() == '\\'))
                                 {
+                                    if (JSON_HEDLEY_UNLIKELY(get() != 'u'))
+                                    {
+                                        // current is the character escaped by the backslash
+                                        error_message = "invalid string: surrogate U+D800..U+DBFF must be followed by U+DC00..U+DFFF";
+                                        error_cause = error_kind::string_invalid_escape;
+                                        string_error_resume = resume_kind::escaped_character;
+                                        return token_type::parse_error;
+                                    }
+
                                     const int codepoint2 = get_codepoint();
 
                                     if (JSON_HEDLEY_UNLIKELY(codepoint2 == -1))
                                     {
                                         error_message = "invalid string: '\\u' must be followed by 4 hex digits";
+                                        error_cause = error_kind::string_invalid_escape;
                                         return token_type::parse_error;
                                     }
 
@@ -603,25 +630,23 @@ class lexer : public lexer_base<BasicJsonType>
                                     if (JSON_HEDLEY_LIKELY(0xDC00 <= codepoint2 && codepoint2 <= 0xDFFF))
                                     {
                                         // overwrite codepoint
-                                        codepoint = static_cast<int>(
-                                                        // high surrogate occupies the most significant 22 bits
-                                                        (static_cast<unsigned int>(codepoint1) << 10u)
-                                                        // low surrogate occupies the least significant 15 bits
-                                                        + static_cast<unsigned int>(codepoint2)
-                                                        // there is still the 0xD800, 0xDC00, and 0x10000 noise
-                                                        // in the result, so we have to subtract with:
-                                                        // (0xD800 << 10) + DC00 - 0x10000 = 0x35FDC00
-                                                        - 0x35FDC00u);
+                                        codepoint = combine_surrogates(codepoint1, codepoint2);
                                     }
                                     else
                                     {
+                                        // the second escape was read completely and is a
+                                        // code point of its own
                                         error_message = "invalid string: surrogate U+D800..U+DBFF must be followed by U+DC00..U+DFFF";
+                                        error_cause = error_kind::string_invalid_escape;
+                                        string_error_resume = resume_kind::after_escape;
+                                        string_error_codepoint = codepoint2;
                                         return token_type::parse_error;
                                     }
                                 }
                                 else
                                 {
                                     error_message = "invalid string: surrogate U+D800..U+DBFF must be followed by U+DC00..U+DFFF";
+                                    error_cause = error_kind::string_invalid_escape;
                                     return token_type::parse_error;
                                 }
                             }
@@ -629,7 +654,10 @@ class lexer : public lexer_base<BasicJsonType>
                             {
                                 if (JSON_HEDLEY_UNLIKELY(0xDC00 <= codepoint1 && codepoint1 <= 0xDFFF))
                                 {
+                                    // the escape was read completely
                                     error_message = "invalid string: surrogate U+DC00..U+DFFF must follow U+D800..U+DBFF";
+                                    error_cause = error_kind::string_invalid_escape;
+                                    string_error_resume = resume_kind::after_escape;
                                     return token_type::parse_error;
                                 }
                             }
@@ -638,10 +666,7 @@ class lexer : public lexer_base<BasicJsonType>
                             JSON_ASSERT(0x00 <= codepoint && codepoint <= 0x10FFFF);
 
                             // translate codepoint into bytes
-                            encode_utf8(static_cast<std::uint32_t>(codepoint), [this](std::uint32_t byte)
-                            {
-                                add(static_cast<char_int_type>(byte));
-                            });
+                            add_codepoint(codepoint);
 
                             break;
                         }
@@ -649,6 +674,7 @@ class lexer : public lexer_base<BasicJsonType>
                         // other characters after escape
                         default:
                             error_message = "invalid string: forbidden character after backslash";
+                            error_cause = error_kind::string;
                             return token_type::parse_error;
                     }
 
@@ -725,6 +751,7 @@ class lexer : public lexer_base<BasicJsonType>
                         }
                     };
                     error_message = control_character_messages[static_cast<std::size_t>(current)];
+                    error_cause = error_kind::string;
                     return token_type::parse_error;
                 }
 
@@ -947,6 +974,7 @@ class lexer : public lexer_base<BasicJsonType>
                 default:
                 {
                     error_message = "invalid string: ill-formed UTF-8 byte";
+                    error_cause = error_kind::string_ill_formed_utf8;
                     return token_type::parse_error;
                 }
             }
@@ -1002,6 +1030,7 @@ class lexer : public lexer_base<BasicJsonType>
                         case char_traits<char_type>::eof():
                         {
                             error_message = "invalid comment; missing closing '*/'";
+                            error_cause = error_kind::unclosed_comment;
                             return false;
                         }
 
@@ -1032,6 +1061,7 @@ class lexer : public lexer_base<BasicJsonType>
             default:
             {
                 error_message = "invalid comment; expecting '/' or '*' after '/'";
+                error_cause = error_kind::other;
                 return false;
             }
         }
@@ -1157,6 +1187,7 @@ scan_number_minus:
             default:
             {
                 error_message = "invalid number; expected digit after '-'";
+                error_cause = error_kind::number;
                 return token_type::parse_error;
             }
         }
@@ -1243,6 +1274,7 @@ scan_number_decimal1:
             default:
             {
                 error_message = "invalid number; expected digit after '.'";
+                error_cause = error_kind::number;
                 return token_type::parse_error;
             }
         }
@@ -1311,6 +1343,7 @@ scan_number_exponent:
             {
                 error_message =
                     "invalid number; expected '+', '-', or digit after exponent";
+                error_cause = error_kind::number;
                 return token_type::parse_error;
             }
         }
@@ -1337,6 +1370,7 @@ scan_number_sign:
             default:
             {
                 error_message = "invalid number; expected digit after exponent sign";
+                error_cause = error_kind::number;
                 return token_type::parse_error;
             }
         }
@@ -1764,6 +1798,7 @@ scan_number_done:
             if (JSON_HEDLEY_UNLIKELY(char_traits<char_type>::to_char_type(get()) != static_cast<char_type>(rest[i])))
             {
                 error_message = "invalid literal";
+                error_cause = error_kind::other;
                 return token_type::parse_error;
             }
         }
@@ -2154,17 +2189,25 @@ scan_number_done:
         return position.chars_read_total;
     }
 
-    /// seekable adapter: count the lines in the consumed input; O(input read
-    /// so far), but only called on errors
+    /// seekable adapter: count the lines in the consumed input. Only the
+    /// input consumed since the previous call is scanned, so a parse that
+    /// reports many errors (a SAX parser recovering from them) stays linear
+    /// in the input instead of rescanning it for every error.
     position_t get_position_impl(std::true_type /*lazy*/) const
     {
         position_t result;
         result.chars_read_total = get_chars_read_total();
         // reads at EOF count as characters but are not part of the input
         const std::size_t consumed = (std::min)(result.chars_read_total, ia.get_consumed_count());
-        std::size_t line_start = 0;
-        result.lines_read = ia.count_consumed_lines(consumed, line_start);
-        result.chars_read_current_line = result.chars_read_total - line_start;
+        if (JSON_HEDLEY_UNLIKELY(consumed < position_cache.consumed))
+        {
+            // the consumed input never shrinks; recount from the start if it did
+            position_cache = {};
+        }
+        position_cache.lines += ia.count_consumed_lines(position_cache.consumed, consumed, position_cache.line_start);
+        position_cache.consumed = consumed;
+        result.lines_read = position_cache.lines;
+        result.chars_read_current_line = result.chars_read_total - position_cache.line_start;
         return result;
     }
 
@@ -2348,6 +2391,7 @@ scan_number_done:
         if (get_chars_read_total() == 0 && !skip_bom())
         {
             error_message = "invalid BOM; must be 0xEF 0xBB 0xBF if given";
+            error_cause = error_kind::other;
             return token_type::parse_error;
         }
 
@@ -2455,10 +2499,583 @@ scan_number_done:
             // error
             default:
                 error_message = "invalid literal";
+                error_cause = error_kind::other;
                 return token_type::parse_error;
         }
     }
 
+  public:
+    /////////////////////
+    // error recovery
+    /////////////////////
+
+    /*!
+    @brief make the best of the token that scan() rejected
+
+    Called by the parser after scan() returned token_type::parse_error and the
+    SAX parser asked to recover from the error (see #3989). Keeps what can be
+    read of the token and skips the rest:
+
+    - A string keeps its characters. An unknown escape stands for the escaped
+      character itself (as in JavaScript), an invalid Unicode escape and ill-formed
+      UTF-8 become U+FFFD, and a control character is kept. A line break or the
+      end of the input ends a string that lacks its closing quote.
+    - A number keeps its longest valid prefix, e.g. `1` for `1.` or `1e+`.
+    - A block comment that is not closed runs to the end of the input.
+    - Anything else is skipped.
+
+    The rest of an invalid token is skipped up to the next delimiter
+    (whitespace, a structural character, or a quote). A delimiter that the
+    invalid token consumed is returned to the input, so that the next scan()
+    reads it.
+
+    @return token_type::value_string or a number token type if a string or a
+            number could be read, token_type::end_of_input for a block comment
+            that is not closed, token_type::uninitialized otherwise
+    */
+    token_type recover_token()
+    {
+        const resume_kind resume = string_error_resume;
+        const int codepoint = string_error_codepoint;
+        string_error_resume = resume_kind::character;
+        string_error_codepoint = -1;
+
+        const error_kind cause = error_cause;
+        error_cause = error_kind::other;
+
+        switch (cause)
+        {
+            case error_kind::string:
+            case error_kind::string_invalid_escape:
+            case error_kind::string_ill_formed_utf8:
+                return recover_string(cause, resume, codepoint);
+
+            case error_kind::number:
+                return recover_number();
+
+            case error_kind::unclosed_comment:
+                // the comment runs to the end of the input
+                return token_type::end_of_input;
+
+            case error_kind::other:
+            default:
+                skip_to_delimiter();
+                return token_type::uninitialized;
+        }
+    }
+
+    /*!
+    @brief return the token that scan() read last to the input, so that the
+           next scan() reads it again
+
+    Called by the parser when recovering from an error. The token must be a
+    single character (',', ':', '[', ']', '{', or '}') or the end of the
+    input, and scan() must have read it last.
+    */
+    void unget_token()
+    {
+        JSON_ASSERT(!next_unget);
+        unget();
+    }
+
+    /*!
+    @brief let the token string for the next error begin at the current character
+
+    The token string of an error reaches back to the beginning of the last
+    string or number. After an error, the parser calls this function so that
+    the next error does not report (and, with many errors, copy) everything
+    read since then.
+    */
+    void restart_token_string()
+    {
+        restart_token_string_impl(std::integral_constant<bool, lazy_token_string> {});
+    }
+
+  private:
+    /// how recover_string() continues after the error scan_string() reported
+    enum class resume_kind : std::uint8_t
+    {
+        /// current is the next character of the string (or the end of input)
+        character,
+        /// current is the character escaped by the preceding backslash
+        escaped_character,
+        /// current is the last character of a complete escape
+        after_escape
+    };
+
+    /// what kind of token scan() rejected, which decides how recover_token() repairs it
+    enum class error_kind : std::uint8_t
+    {
+        /// anything not listed below; skipped up to the next delimiter
+        other,
+        /// a string
+        string,
+        /// a string with an invalid Unicode escape, which becomes U+FFFD
+        string_invalid_escape,
+        /// a string with ill-formed UTF-8, which becomes U+FFFD
+        string_ill_formed_utf8,
+        /// a number
+        number,
+        /// a block comment that is not closed
+        unclosed_comment
+    };
+
+    /// whether current ends an invalid token (see recover_token())
+    bool current_is_delimiter() const noexcept
+    {
+        switch (current)
+        {
+            case ' ':
+            case '\t':
+            case '\n':
+            case '\r':
+            case '[':
+            case ']':
+            case '{':
+            case '}':
+            case ',':
+            case ':':
+            case '\"':
+#if !JSON_STRICT_NUL_HANDLING
+            case '\0':
+#endif
+            case char_traits<char_type>::eof():
+                return true;
+
+            case '/':
+                return ignore_comments;
+
+            default:
+                return false;
+        }
+    }
+
+    /// skip the rest of an invalid token and return its delimiter to the input
+    void skip_to_delimiter()
+    {
+        while (!current_is_delimiter())
+        {
+            get();
+        }
+
+        if (current != char_traits<char_type>::eof())
+        {
+            unget();
+        }
+    }
+
+    /// append U+FFFD REPLACEMENT CHARACTER to token_buffer
+    void add_replacement_character()
+    {
+        add_codepoint(0xFFFD);
+    }
+
+    /// append the UTF-8 encoding of @a codepoint (not a surrogate) to token_buffer
+    void add_codepoint(const int codepoint)
+    {
+        JSON_ASSERT(0x00 <= codepoint && codepoint <= 0x10FFFF);
+        encode_utf8(static_cast<std::uint32_t>(codepoint), [this](std::uint32_t byte)
+        {
+            add(static_cast<char_int_type>(byte));
+        });
+    }
+
+    /// append a code point read from a Unicode escape; a surrogate becomes U+FFFD
+    void add_escaped_codepoint(const int codepoint)
+    {
+        if (0xD800 <= codepoint && codepoint <= 0xDFFF)
+        {
+            add_replacement_character();
+        }
+        else
+        {
+            add_codepoint(codepoint);
+        }
+    }
+
+    /*!
+    @brief remove an incomplete UTF-8 sequence from the end of token_buffer
+
+    next_byte_in_range() adds the bytes of a sequence as it checks them, so
+    when it rejects a byte, the beginning of the sequence is already in
+    token_buffer, which otherwise holds only complete sequences.
+
+    @return whether an incomplete sequence was removed
+    */
+    bool remove_incomplete_utf8_sequence()
+    {
+        std::size_t lead = token_buffer.size();
+        std::size_t continuation_bytes = 0;
+        while (lead > 0 && continuation_bytes < 3
+                && (static_cast<unsigned char>(token_buffer[lead - 1]) & 0xC0u) == 0x80u)
+        {
+            --lead;
+            ++continuation_bytes;
+        }
+        if (lead == 0)
+        {
+            return false;
+        }
+
+        const auto lead_byte = static_cast<unsigned char>(token_buffer[lead - 1]);
+        std::size_t expected = 0;
+        if (lead_byte >= 0xF0)
+        {
+            expected = 3;
+        }
+        else if (lead_byte >= 0xE0)
+        {
+            expected = 2;
+        }
+        else if (lead_byte >= 0xC0)
+        {
+            expected = 1;
+        }
+        if (continuation_bytes >= expected)
+        {
+            return false;
+        }
+
+        token_buffer.resize(lead - 1);
+        return true;
+    }
+
+    /*!
+    @brief read the UTF-8 sequence that begins with current, which is not ASCII
+    @return whether the next character must be read; false if current still
+            needs to be handled, because it does not belong to the sequence
+    */
+    bool recover_utf8_sequence()
+    {
+        // the number of continuation bytes and the range of the first one;
+        // see the ranges in scan_string()
+        std::size_t count = 0;
+        char_int_type low = 0x80;
+        char_int_type high = 0xBF;
+        if (current >= 0xC2 && current <= 0xDF)
+        {
+            count = 1;
+        }
+        else if (current >= 0xE0 && current <= 0xEF)
+        {
+            count = 2;
+            low = (current == 0xE0) ? 0xA0 : 0x80;
+            high = (current == 0xED) ? 0x9F : 0xBF;
+        }
+        else if (current >= 0xF0 && current <= 0xF4)
+        {
+            count = 3;
+            low = (current == 0xF0) ? 0x90 : 0x80;
+            high = (current == 0xF4) ? 0x8F : 0xBF;
+        }
+        else
+        {
+            // an ill-formed byte
+            add_replacement_character();
+            return true;
+        }
+
+        const std::size_t start = token_buffer.size();
+        add(current);
+        for (std::size_t i = 0; i < count; ++i)
+        {
+            get();
+            if (current < low || current > high)
+            {
+                token_buffer.resize(start);
+                add_replacement_character();
+                return false;
+            }
+            add(current);
+            low = 0x80;
+            high = 0xBF;
+        }
+        return true;
+    }
+
+    /*!
+    @brief read the low surrogate that must follow the high surrogate @a high
+    @return whether the next character must be read; false if current still
+            needs to be handled
+    */
+    bool recover_low_surrogate(int high)
+    {
+        while (true)
+        {
+            if (get() != '\\')
+            {
+                add_replacement_character();
+                return false;
+            }
+            if (get() != 'u')
+            {
+                add_replacement_character();
+                // not 'u', so this does not come back here
+                return recover_escape();
+            }
+
+            const int low = get_codepoint();
+            if (low == -1)
+            {
+                add_replacement_character();
+                return false;
+            }
+            if (0xDC00 <= low && low <= 0xDFFF)
+            {
+                add_codepoint(combine_surrogates(high, low));
+                return true;
+            }
+
+            // high has no low surrogate
+            add_replacement_character();
+            if (low < 0xD800 || low > 0xDBFF)
+            {
+                add_codepoint(low);
+                return true;
+            }
+            // another high surrogate
+            high = low;
+        }
+    }
+
+    /*!
+    @brief read the escape whose backslash was read; current is the escaped character
+    @return whether the next character must be read; false if current still
+            needs to be handled
+    */
+    bool recover_escape()
+    {
+        switch (current)
+        {
+            case '\"':
+                add('\"');
+                return true;
+            case '\\':
+                add('\\');
+                return true;
+            case '/':
+                add('/');
+                return true;
+            case 'b':
+                add('\b');
+                return true;
+            case 'f':
+                add('\f');
+                return true;
+            case 'n':
+                add('\n');
+                return true;
+            case 'r':
+                add('\r');
+                return true;
+            case 't':
+                add('\t');
+                return true;
+
+            case 'u':
+            {
+                const int codepoint = get_codepoint();
+                if (codepoint == -1)
+                {
+                    add_replacement_character();
+                    return false;
+                }
+                if (0xD800 <= codepoint && codepoint <= 0xDBFF)
+                {
+                    return recover_low_surrogate(codepoint);
+                }
+                add_escaped_codepoint(codepoint);
+                return true;
+            }
+
+            // an unknown escape stands for the escaped character
+            default:
+                return false;
+        }
+    }
+
+    /*!
+    @brief read the rest of a string after scan_string() rejected it
+
+    token_buffer holds what scan_string() read before the error. See
+    recover_token() for how errors are repaired.
+
+    @param[in] cause      the kind of error scan_string() reported
+    @param[in] resume     how to continue, see resume_kind
+    @param[in] codepoint  for a high surrogate followed by an escape of another
+                          code point: that code point; -1 otherwise
+    */
+    token_type recover_string(const error_kind cause, const resume_kind resume, const int codepoint)
+    {
+        // whether the next character must be read before it can be handled
+        bool fetch = false;
+
+        if (cause == error_kind::string_invalid_escape
+                || (cause == error_kind::string_ill_formed_utf8 && remove_incomplete_utf8_sequence()))
+        {
+            add_replacement_character();
+        }
+
+        switch (resume)
+        {
+            case resume_kind::escaped_character:
+                fetch = recover_escape();
+                break;
+            case resume_kind::after_escape:
+                if (0xD800 <= codepoint && codepoint <= 0xDBFF)
+                {
+                    fetch = recover_low_surrogate(codepoint);
+                }
+                else
+                {
+                    if (codepoint != -1)
+                    {
+                        add_escaped_codepoint(codepoint);
+                    }
+                    fetch = true;
+                }
+                break;
+            case resume_kind::character:
+            default:
+                break;
+        }
+
+        while (true)
+        {
+            if (fetch)
+            {
+                get();
+            }
+            fetch = true;
+
+            switch (current)
+            {
+                case '\"':
+                // a line break or the end of the input ends a string that
+                // lacks its closing quote
+                case '\n':
+                case '\r':
+                case char_traits<char_type>::eof():
+                    return token_type::value_string;
+
+#if !JSON_STRICT_NUL_HANDLING
+                case '\0':
+                    // the end of the input, see scan()
+                    unget();
+                    return token_type::value_string;
+#endif
+
+                case '\\':
+                    get();
+                    fetch = recover_escape();
+                    break;
+
+                default:
+                    if (current < 0x80)
+                    {
+                        // including control characters
+                        add(current);
+                    }
+                    else
+                    {
+                        fetch = recover_utf8_sequence();
+                    }
+                    break;
+            }
+        }
+    }
+
+    /*!
+    @brief keep the longest valid prefix of a number that scan_number() rejected
+
+    token_buffer holds the characters scan_number() accepted before the error,
+    so the prefix ends at its last digit.
+    */
+    token_type recover_number()
+    {
+        // only size(), operator[], and resize() are used, which every string
+        // type the library supports provides
+        std::size_t length = token_buffer.size();
+        while (length != 0 && (token_buffer[length - 1] < '0' || token_buffer[length - 1] > '9'))
+        {
+            --length;
+        }
+        token_buffer.resize(length);
+
+        if (length == 0)
+        {
+            skip_to_delimiter();
+            return token_type::uninitialized;
+        }
+
+        if (decimal_point_position >= length)
+        {
+            decimal_point_position = std::string::npos;
+        }
+
+        std::size_t exponent = std::string::npos;
+        for (std::size_t i = 0; i < length; ++i)
+        {
+            if (token_buffer[i] == 'e' || token_buffer[i] == 'E')
+            {
+                exponent = i;
+                break;
+            }
+        }
+        const std::size_t mantissa_end = (exponent == std::string::npos) ? length : exponent;
+        token_type number_type = token_type::value_unsigned;
+        if (decimal_point_position != std::string::npos || exponent != std::string::npos)
+        {
+            number_type = token_type::value_float;
+        }
+        else if (token_buffer[0] == '-')
+        {
+            number_type = token_type::value_integer;
+        }
+
+        const token_type result = convert_number(number_type, mantissa_end);
+        skip_to_delimiter();
+        return result;
+    }
+
+    /// seekable or token-tracking adapter: the token string begins at current
+    void restart_token_string_impl(std::true_type /*lazy*/)
+    {
+        restart_token_string_lazy(std::integral_constant<bool, adapter_token> {});
+    }
+
+    /// seekable adapter: the token string begins at current, which was consumed
+    void restart_token_string_lazy(std::false_type /*adapter_token*/) noexcept
+    {
+        const std::size_t consumed = ia.get_consumed_count();
+        token_string_start = (consumed > 0 && current != char_traits<char_type>::eof()) ? consumed - 1 : consumed;
+    }
+
+    /// token-tracking adapter: the token begins with current, or with the next
+    /// character if current was put back or is the end of input
+    void restart_token_string_lazy(std::true_type /*adapter_token*/)
+    {
+        if (!next_unget && current != char_traits<char_type>::eof())
+        {
+            ia.mark_token_start(current);
+        }
+        else
+        {
+            ia.begin_token();
+        }
+    }
+
+    /// streaming adapter: the token string begins at current; a character
+    /// that was put back is copied again when it is read again
+    void restart_token_string_impl(std::false_type /*lazy*/)
+    {
+        token_string.clear();
+        if (!next_unget && current != char_traits<char_type>::eof())
+        {
+            token_string.push_back(char_traits<char_type>::to_char_type(current));
+        }
+    }
+
     /// input adapter
     InputAdapterType ia;
 
@@ -2483,6 +3100,19 @@ scan_number_done:
     /// that unget() can restore the column instead of leaving it at 0
     std::size_t chars_read_before_newline = 0;
 
+    /// seekable adapter: what get_position() counted last, so that the next
+    /// call only scans the input consumed since
+    struct position_cache_t
+    {
+        /// consumed characters scanned so far
+        std::size_t consumed = 0;
+        /// newlines among them
+        std::size_t lines = 0;
+        /// index after the last of these newlines
+        std::size_t line_start = 0;
+    };
+    mutable position_cache_t position_cache {};
+
     /// raw input token string for error messages; only populated for streaming
     /// adapters (seekable adapters reconstruct it lazily via token_string_start)
     std::vector<char_type> token_string {};
@@ -2503,6 +3133,15 @@ scan_number_done:
     /// a description of occurred lexer errors
     const char* error_message = "";
 
+    /// what kind of token scan() rejected; set together with error_message
+    error_kind error_cause = error_kind::other;
+    /// how recover_token() continues a string that scan_string() rejected;
+    /// set only on the error paths that need more than error_message
+    resume_kind string_error_resume = resume_kind::character;
+    /// the code point of the second escape when a high surrogate is followed
+    /// by an escape that is not a low surrogate; -1 otherwise
+    int string_error_codepoint = -1;
+
     // number values
     number_integer_t value_integer = 0;
     number_unsigned_t value_unsigned = 0;

include/nlohmann/detail/input/parser.hpp

@@ -153,25 +153,72 @@ class parser
     bool accept(const bool strict = true)
     {
         json_sax_acceptor<BasicJsonType> sax_acceptor;
-        return sax_parse(&sax_acceptor, strict);
+        return sax_parse_impl<false>(&sax_acceptor, strict);
     }
 
+    /*!
+    @brief public SAX interface
+
+    If the SAX parser's parse_error() returns true, the parser recovers from
+    the error: it repairs the input and continues (see #3989).
+
+    @param[in] sax     the SAX parser
+    @param[in] strict  whether to expect the last token to be EOF
+    @return whether the input was parsed without errors and no SAX event
+            returned false
+    */
     template<typename SAX>
     JSON_HEDLEY_NON_NULL(2)
     bool sax_parse(SAX* sax, const bool strict = true)
     {
-        (void)detail::is_sax_static_asserts<SAX, BasicJsonType> {};
-        const bool result = sax_parse_internal(sax);
-
-        if (result)
-        {
-            return finish_input(*sax, strict);
-        }
-
-        return false;
+        return sax_parse_impl<true>(sax, strict);
     }
 
   private:
+    /// what sax_parse_internal() does after an object key was expected
+    enum class next_step : std::uint8_t
+    {
+        /// stop parsing
+        stop,
+        /// parse a value that begins with last_token
+        parse_value,
+        /// evaluate the state of the innermost container, which reads
+        /// last_token again
+        evaluate_state
+    };
+
+    template<bool AllowRecovery, typename SAX>
+    JSON_HEDLEY_NON_NULL(2)
+    bool sax_parse_impl(SAX* sax, const bool strict)
+    {
+        (void)detail::is_sax_static_asserts<SAX, BasicJsonType> {};
+        const bool result = sax_parse_internal<AllowRecovery>(sax);
+
+        if (result)
+        {
+            if (strict)
+            {
+                // strict mode: next byte must be EOF; after recovering from an
+                // error, the end of the input may already have been read
+                if (last_token != token_type::end_of_input && get_token() != token_type::end_of_input)
+                {
+                    // the value is complete, so there is nothing to recover
+                    static_cast<void>(report_error(sax, parse_error::create(exception_id::syntax_error, m_lexer.get_position(), exception_message(token_type::end_of_input, "value"), nullptr),
+                                                   std::integral_constant<bool, AllowRecovery> {}));
+                    return false;
+                }
+            }
+            else
+            {
+                // the caller keeps using the input: position it right after
+                // the value by leaving the character that terminated it
+                m_lexer.release_lookahead();
+            }
+        }
+
+        return result && !error_reported;
+    }
+
     /// the text of the current float token for @a sax (see sax_ignores_number_text)
     template<typename SAX>
     const string_t& number_float_text(SAX* /*sax*/)
@@ -239,17 +286,26 @@ class parser
     template<typename DomSax>
     bool parse_dom(DomSax& sdp, const bool strict)
     {
-        sax_parse_internal(&sdp);
+        sax_parse_internal<false>(&sdp);
 
         static_cast<void>(finish_input(sdp, strict));
 
         return !sdp.is_errored();
     }
 
-    template<typename SAX>
+    /*!
+    @brief parse a JSON value and pass it to a SAX parser
+
+    @tparam AllowRecovery  whether to recover from an error if the SAX parser's
+                           parse_error() returns true; false for the SAX parsers
+                           of parse() and accept(), which never do, so that no
+                           code for recovering is generated for them
+    */
+    template<bool AllowRecovery, typename SAX>
     JSON_HEDLEY_NON_NULL(2)
     bool sax_parse_internal(SAX* sax)
     {
+        const std::integral_constant<bool, AllowRecovery> allow_recovery{};
         // value to avoid a goto (see comment where set to true)
         bool skip_to_state_evaluation = false;
 
@@ -288,10 +344,18 @@ class parser
                             break;
                         }
 
-                        // parse key
+                        // remember we are now inside an object
+                        states.push_back(0);
+
+                        // parse key (the steps of parse_key(), which are
+                        // repeated here and below for speed)
                         if (JSON_HEDLEY_UNLIKELY(last_token != token_type::value_string))
                         {
-                            return syntax_error(*sax, exception_message(token_type::value_string, "object key"));
+                            if (!continue_after(key_error(sax, allow_recovery, false), skip_to_state_evaluation))
+                            {
+                                return false;
+                            }
+                            continue;
                         }
                         if (JSON_HEDLEY_UNLIKELY(!sax->key(m_lexer.get_string_token())))
                         {
@@ -301,12 +365,13 @@ class parser
                         // parse separator (:)
                         if (JSON_HEDLEY_UNLIKELY(!get_token_expecting(token_type::name_separator)))
                         {
-                            return syntax_error(*sax, exception_message(token_type::name_separator, "object separator"));
+                            if (!continue_after(key_error(sax, allow_recovery, true), skip_to_state_evaluation))
+                            {
+                                return false;
+                            }
+                            continue;
                         }
 
-                        // remember we are now inside an object
-                        states.push_back(0);
-
                         // parse values
                         get_token();
                         continue;
@@ -342,9 +407,11 @@ class parser
 
                         if (JSON_HEDLEY_UNLIKELY(!std::isfinite(res)))
                         {
-                            return sax->parse_error(m_lexer.get_position(),
-                                                    m_lexer.get_token_string(),
-                                                    out_of_range::create(exception_id::number_overflow, concat("number overflow parsing '", m_lexer.get_token_string(), '\''), nullptr));
+                            if (!overflow_error(sax, res, allow_recovery))
+                            {
+                                return false;
+                            }
+                            break;
                         }
 
                         if (JSON_HEDLEY_UNLIKELY(!sax->number_float(res, number_float_text(sax))))
@@ -412,16 +479,63 @@ class parser
                     case token_type::parse_error:
                     {
                         // using "uninitialized" to avoid an "expected" message
-                        return syntax_error(*sax, exception_message(token_type::uninitialized, "value"));
+                        if (!report_error(sax, parse_error::create(exception_id::syntax_error, m_lexer.get_position(), exception_message(token_type::uninitialized, "value"), nullptr), allow_recovery))
+                        {
+                            return false;
+                        }
+
+                        // recover: keep what can be read of the token
+                        recover_token(allow_recovery);
+                        if (last_token != token_type::uninitialized)
+                        {
+                            // a string or a number
+                            continue;
+                        }
+                        if (states.empty())
+                        {
+                            // look for the value after the garbage
+                            if (!skip_to_value(allow_recovery))
+                            {
+                                return false;
+                            }
+                            continue;
+                        }
+                        // nothing could be read
+                        if (JSON_HEDLEY_UNLIKELY(!sax->null()))
+                        {
+                            return false;
+                        }
+                        break;
                     }
                     case token_type::end_of_input:
                     {
                         if (JSON_HEDLEY_UNLIKELY(m_lexer.get_chars_read_total() == 1))
                         {
-                            return syntax_error(*sax, empty_input_message());
+                            // there is nothing to recover
+                            static_cast<void>(report_error(sax, parse_error::create(exception_id::syntax_error, m_lexer.get_position(),
+                                                           empty_input_message(), nullptr), allow_recovery));
+                            return false;
                         }
 
-                        return syntax_error(*sax, exception_message(token_type::literal_or_value, "value"));
+                        if (!report_error(sax, parse_error::create(exception_id::syntax_error, m_lexer.get_position(), exception_message(token_type::literal_or_value, "value"), nullptr), allow_recovery))
+                        {
+                            return false;
+                        }
+
+                        // recover: the input ends where a value is missing
+                        if (states.empty())
+                        {
+                            // there is no value
+                            return false;
+                        }
+                        if (!recover_missing_value(sax, states, allow_recovery))
+                        {
+                            return false;
+                        }
+                        // the state evaluation reads the token again
+                        unget_token(allow_recovery);
+                        skip_to_state_evaluation = true;
+                        continue;
                     }
                     case token_type::uninitialized:
                     case token_type::end_array:
@@ -431,7 +545,35 @@ class parser
                     case token_type::literal_or_value:
                     default: // the last token was unexpected
                     {
-                        return syntax_error(*sax, exception_message(token_type::literal_or_value, "value"));
+                        if (!report_error(sax, parse_error::create(exception_id::syntax_error, m_lexer.get_position(), exception_message(token_type::literal_or_value, "value"), nullptr), allow_recovery))
+                        {
+                            return false;
+                        }
+
+                        // recover
+                        if (states.empty())
+                        {
+                            // look for the value after the garbage
+                            if (!skip_to_value(allow_recovery))
+                            {
+                                return false;
+                            }
+                            continue;
+                        }
+                        if (last_token == token_type::name_separator)
+                        {
+                            // a stray ':'; the value may follow
+                            get_token();
+                            continue;
+                        }
+                        if (!recover_missing_value(sax, states, allow_recovery))
+                        {
+                            return false;
+                        }
+                        // the state evaluation reads the token again
+                        unget_token(allow_recovery);
+                        skip_to_state_evaluation = true;
+                        continue;
                     }
                 }
             }
@@ -482,7 +624,30 @@ class parser
                     continue;
                 }
 
-                return syntax_error(*sax, exception_message(token_type::end_array, "array"));
+                if (!report_error(sax, parse_error::create(exception_id::syntax_error, m_lexer.get_position(), exception_message(token_type::end_array, "array"), nullptr), allow_recovery))
+                {
+                    return false;
+                }
+
+                // recover
+                if (last_token == token_type::end_of_input)
+                {
+                    // the input ends inside the array
+                    return close_containers(sax, states, allow_recovery);
+                }
+                if (last_token == token_type::end_object)
+                {
+                    // a wrong closing bracket closes the innermost container
+                    if (JSON_HEDLEY_UNLIKELY(!sax->end_array()))
+                    {
+                        return false;
+                    }
+                    states.pop_back();
+                    skip_to_state_evaluation = true;
+                }
+                // otherwise, a missing ',' (or a stray ':', which value
+                // parsing drops): the next value begins here
+                continue;
             }
 
             // states.back() is false -> object
@@ -499,9 +664,12 @@ class parser
                     // parse key
                     if (JSON_HEDLEY_UNLIKELY(last_token != token_type::value_string))
                     {
-                        return syntax_error(*sax, exception_message(token_type::value_string, "object key"));
+                        if (!continue_after(key_error(sax, allow_recovery, false), skip_to_state_evaluation))
+                        {
+                            return false;
+                        }
+                        continue;
                     }
-
                     if (JSON_HEDLEY_UNLIKELY(!sax->key(m_lexer.get_string_token())))
                     {
                         return false;
@@ -510,7 +678,11 @@ class parser
                     // parse separator (:)
                     if (JSON_HEDLEY_UNLIKELY(!get_token_expecting(token_type::name_separator)))
                     {
-                        return syntax_error(*sax, exception_message(token_type::name_separator, "object separator"));
+                        if (!continue_after(key_error(sax, allow_recovery, true), skip_to_state_evaluation))
+                        {
+                            return false;
+                        }
+                        continue;
                     }
 
                     // parse values
@@ -538,10 +710,546 @@ class parser
                 continue;
             }
 
-            return syntax_error(*sax, exception_message(token_type::end_object, "object"));
+            if (!report_error(sax, parse_error::create(exception_id::syntax_error, m_lexer.get_position(), exception_message(token_type::end_object, "object"), nullptr), allow_recovery))
+            {
+                return false;
+            }
+
+            // recover
+            if (last_token == token_type::end_of_input)
+            {
+                // the input ends inside the object
+                return close_containers(sax, states, allow_recovery);
+            }
+            if (last_token == token_type::end_array)
+            {
+                // a wrong closing bracket closes the innermost container
+                if (JSON_HEDLEY_UNLIKELY(!sax->end_object()))
+                {
+                    return false;
+                }
+                states.pop_back();
+                skip_to_state_evaluation = true;
+                continue;
+            }
+            if (!continue_after(recover_member(sax, allow_recovery), skip_to_state_evaluation))
+            {
+                return false;
+            }
         }
     }
 
+    /*!
+    @brief continue sax_parse_internal() after a recovery
+    @return whether to continue parsing
+    */
+    bool continue_after(const next_step step, bool& skip_to_state_evaluation)
+    {
+        if (step == next_step::evaluate_state)
+        {
+            // the state evaluation reads the token again
+            m_lexer.unget_token();
+            skip_to_state_evaluation = true;
+        }
+        return step != next_step::stop;
+    }
+
+    /// the parser for parse() and accept() never recovers: stop parsing
+    JSON_INTERNAL_ALWAYS_INLINE
+    static std::false_type continue_after(std::false_type /*step*/, bool& /*skip_to_state_evaluation*/) noexcept
+    {
+        return {};
+    }
+
+    /*!
+    @brief parse an object key and the name separator (:) after it
+
+    last_token is the token where the key is expected. sax_parse_internal()
+    repeats these steps rather than calling this function, which is used
+    when recovering from an error.
+
+    @return next_step::parse_value if the value follows, with last_token its
+            first token; next_step::evaluate_state if the object's state is
+            to be evaluated after recovering from an error; next_step::stop
+            to stop parsing
+    */
+    template<typename SAX>
+    next_step parse_key(SAX* sax)
+    {
+        const std::true_type allow_recovery{};
+
+        if (JSON_HEDLEY_UNLIKELY(last_token != token_type::value_string))
+        {
+            return key_error(sax, allow_recovery, false);
+        }
+
+        if (JSON_HEDLEY_UNLIKELY(!sax->key(m_lexer.get_string_token())))
+        {
+            return next_step::stop;
+        }
+
+        // parse separator (:)
+        if (JSON_HEDLEY_UNLIKELY(get_token() != token_type::name_separator))
+        {
+            return key_error(sax, allow_recovery, true);
+        }
+
+        // the value begins with the next token
+        get_token();
+        return next_step::parse_value;
+    }
+
+    /*!
+    @brief report a number that is too large for number_float_t, and recover
+           from the error by passing the value on; the SAX parser gets the
+           number's text as well
+
+    This is a separate function, as reading other numbers is measurably
+    slower if the error is handled where they are read.
+
+    @param[in] sax    the SAX parser
+    @param[in] value  the value that is not finite
+    @return whether to continue parsing
+    */
+    template<typename SAX>
+    bool overflow_error(SAX* sax, const number_float_t value, std::true_type allow_recovery)
+    {
+        if (!report_error(sax, out_of_range::create(exception_id::number_overflow, concat("number overflow parsing '", m_lexer.get_token_string(), '\''), nullptr), allow_recovery))
+        {
+            return false;
+        }
+        return sax->number_float(value, number_float_text(sax));
+    }
+
+    /// @copydoc overflow_error
+    template<typename SAX>
+    JSON_INTERNAL_ALWAYS_INLINE
+    std::false_type overflow_error(SAX* sax, const number_float_t /*value*/, std::false_type allow_recovery)
+    {
+        return report_error(sax, out_of_range::create(exception_id::number_overflow, concat("number overflow parsing '", m_lexer.get_token_string(), '\''), nullptr), allow_recovery);
+    }
+
+    /*!
+    @brief report a missing key, or a missing name separator (:) after the
+           key; the parser for parse() and accept() never recovers
+
+    @param[in] key_read  whether the key was read, so that the name separator
+                         is missing
+    @return std::false_type, see report_error()
+    */
+    template<typename SAX>
+    JSON_INTERNAL_ALWAYS_INLINE
+    std::false_type key_error(SAX* sax, std::false_type allow_recovery, const bool key_read)
+    {
+        return report_error(sax, parse_error::create(exception_id::syntax_error, m_lexer.get_position(), key_read
+                            ? exception_message(token_type::name_separator, "object separator")
+                            : exception_message(token_type::value_string, "object key"), nullptr), allow_recovery);
+    }
+
+    /*!
+    @brief report a missing key, or a missing name separator (:) after the
+           key, and recover from it
+
+    @param[in] key_read  whether the key was read, so that the name separator
+                         is missing
+    */
+    template<typename SAX>
+    next_step key_error(SAX* sax, std::true_type allow_recovery, const bool key_read)
+    {
+        if (!key_read)
+        {
+            if (!report_error(sax, parse_error::create(exception_id::syntax_error, m_lexer.get_position(), exception_message(token_type::value_string, "object key"), nullptr), allow_recovery))
+            {
+                return next_step::stop;
+            }
+            return recover_key(sax);
+        }
+
+        if (!report_error(sax, parse_error::create(exception_id::syntax_error, m_lexer.get_position(), exception_message(token_type::name_separator, "object separator"), nullptr), allow_recovery))
+        {
+            return next_step::stop;
+        }
+        return recover_name_separator(sax);
+    }
+
+    /////////////////////
+    // error recovery
+    /////////////////////
+
+    /*
+    The functions below repair an error after the SAX parser's parse_error()
+    returned true (see #3989). Each mistake is repaired by the smallest local
+    edit: a missing ',' or ':' is inserted, a stray token is removed, what can
+    be read of an invalid string or number is kept (see
+    lexer::recover_token()), a missing value becomes null, a wrong closing
+    bracket closes the innermost container, and the end of the input closes
+    all of them. The events stay balanced, and every key() is followed by
+    exactly one value.
+
+    A repair hands a token to the state evaluation, by returning it to the
+    lexer (lexer::unget_token()) so that the state evaluation reads it again,
+    only if it is ',', ']', '}', or the end of the input. The state evaluation
+    hands a token to value or key parsing only if it is none of them, so a
+    token is never handed back and forth. Every other step reads a token or
+    closes a container, so parsing always ends.
+    */
+
+    /*!
+    @brief report an error to the SAX parser; the parser for parse() and
+           accept() never recovers
+
+    @return std::false_type rather than false: its value is known where the
+            function is called even if the call is not inlined, so the code
+            for recovering is not generated
+    */
+    template<typename SAX, typename Exception>
+    JSON_INTERNAL_ALWAYS_INLINE
+    std::false_type report_error(SAX* sax, const Exception& ex, std::false_type /*allow_recovery*/)
+    {
+        static_cast<void>(sax); // MSVC 2015 does not count calling a static parse_error() as using it
+        error_reported = true;
+        static_cast<void>(sax->parse_error(m_lexer.get_position(), m_lexer.get_token_string(), ex));
+        return {};
+    }
+
+    /*!
+    @brief report an error to the SAX parser
+    @return whether to recover from the error
+    */
+    template<typename SAX, typename Exception>
+    bool report_error(SAX* sax, const Exception& ex, std::true_type /*allow_recovery*/)
+    {
+        static_cast<void>(sax); // MSVC 2015 does not count calling a static parse_error() as using it
+        const std::size_t position = m_lexer.get_position().chars_read_total;
+        if (error_reported && position == last_error_position && last_token == last_error_token)
+        {
+            // a repair handed on the token of the error it repaired; the
+            // token was reported already, and the SAX parser asked to recover
+            return true;
+        }
+
+        error_reported = true;
+        last_error_position = position;
+        last_error_token = last_token;
+
+        if (!sax->parse_error(m_lexer.get_position(), m_lexer.get_token_string(), ex))
+        {
+            return false;
+        }
+
+        // the token string of the next error begins here
+        m_lexer.restart_token_string();
+        return true;
+    }
+
+    /*!
+    @brief keep what can be read of the token that the lexer rejected
+
+    The error was reported for the rejected token, so it is not reported again
+    for the token it is repaired to (see lexer::recover_token()).
+    */
+    token_type recover_token()
+    {
+        last_token = m_lexer.recover_token();
+        last_error_position = m_lexer.get_position().chars_read_total;
+        last_error_token = last_token;
+        return last_token;
+    }
+
+    // The functions below are called from sax_parse_internal() after an error
+    // was reported. The parser for parse() and accept() stopped there, so for
+    // it they are stubs: the code for recovering is then not even referenced,
+    // and unoptimized builds do not emit it either.
+
+    /// @copydoc recover_token()
+    JSON_INTERNAL_ALWAYS_INLINE
+    token_type recover_token(std::true_type /*allow_recovery*/)
+    {
+        return recover_token();
+    }
+
+    /// @copydoc recover_token()
+    JSON_INTERNAL_ALWAYS_INLINE
+    static std::false_type recover_token(std::false_type /*allow_recovery*/) noexcept
+    {
+        return {};
+    }
+
+    /// return the token that was read last to the lexer (see lexer::unget_token())
+    JSON_INTERNAL_ALWAYS_INLINE
+    void unget_token(std::true_type /*allow_recovery*/)
+    {
+        m_lexer.unget_token();
+    }
+
+    /// @copydoc unget_token(std::true_type)
+    JSON_INTERNAL_ALWAYS_INLINE
+    static void unget_token(std::false_type /*allow_recovery*/) noexcept {}
+
+    /// @copydoc skip_to_value
+    JSON_INTERNAL_ALWAYS_INLINE
+    static std::false_type skip_to_value(std::false_type /*allow_recovery*/) noexcept
+    {
+        return {};
+    }
+
+    /// @copydoc recover_missing_value
+    template<typename SAX>
+    JSON_INTERNAL_ALWAYS_INLINE
+    static std::false_type recover_missing_value(SAX* /*sax*/, const std::vector<std::uint8_t>& /*states*/, std::false_type /*allow_recovery*/) noexcept
+    {
+        return {};
+    }
+
+    /// pass the end events of all open containers
+    template<typename SAX>
+    bool close_containers(SAX* sax, std::vector<std::uint8_t>& states, std::true_type /*allow_recovery*/)
+    {
+        while (!states.empty())
+        {
+            const bool is_array = states.back() != 0;
+            states.pop_back();
+            if (JSON_HEDLEY_UNLIKELY(is_array ? !sax->end_array() : !sax->end_object()))
+            {
+                return false;
+            }
+        }
+        return true;
+    }
+
+    /// @copydoc close_containers
+    template<typename SAX>
+    JSON_INTERNAL_ALWAYS_INLINE
+    static std::false_type close_containers(SAX* /*sax*/, std::vector<std::uint8_t>& /*states*/, std::false_type /*allow_recovery*/) noexcept
+    {
+        return {};
+    }
+
+    /*!
+    @brief read tokens until one begins a value, skipping everything before
+           the top-level value
+    @return whether a value begins with last_token
+    */
+    bool skip_to_value(std::true_type /*allow_recovery*/)
+    {
+        while (true)
+        {
+            switch (get_token())
+            {
+                case token_type::begin_array:
+                case token_type::begin_object:
+                case token_type::literal_false:
+                case token_type::literal_null:
+                case token_type::literal_true:
+                case token_type::value_float:
+                case token_type::value_integer:
+                case token_type::value_string:
+                case token_type::value_unsigned:
+                    return true;
+
+                case token_type::end_of_input:
+                    return false;
+
+                case token_type::parse_error:
+                    recover_token();
+                    if (last_token != token_type::uninitialized)
+                    {
+                        return true;
+                    }
+                    break;
+
+                case token_type::uninitialized:
+                case token_type::end_array:
+                case token_type::end_object:
+                case token_type::name_separator:
+                case token_type::value_separator:
+                case token_type::literal_or_value:
+                default:
+                    break;
+            }
+        }
+    }
+
+    /*!
+    @brief skip the rest of an object member that cannot be read
+
+    Reads tokens, beginning with last_token, until a ',', '}', or ']' that is
+    not inside a container that begins in the skipped tokens, or the end of
+    the input.
+    */
+    void skip_member()
+    {
+        std::size_t depth = 0;
+        while (true)
+        {
+            switch (last_token)
+            {
+                case token_type::begin_array:
+                case token_type::begin_object:
+                    ++depth;
+                    break;
+
+                case token_type::end_array:
+                case token_type::end_object:
+                    if (depth == 0)
+                    {
+                        return;
+                    }
+                    --depth;
+                    break;
+
+                case token_type::value_separator:
+                    if (depth == 0)
+                    {
+                        return;
+                    }
+                    break;
+
+                case token_type::end_of_input:
+                    return;
+
+                case token_type::parse_error:
+                    recover_token();
+                    break;
+
+                case token_type::uninitialized:
+                case token_type::literal_true:
+                case token_type::literal_false:
+                case token_type::literal_null:
+                case token_type::value_string:
+                case token_type::value_unsigned:
+                case token_type::value_integer:
+                case token_type::value_float:
+                case token_type::name_separator:
+                case token_type::literal_or_value:
+                default:
+                    break;
+            }
+            get_token();
+        }
+    }
+
+    /*!
+    @brief pass a value where it is missing
+
+    last_token is ',', ']', '}', or the end of the input, where a value was
+    expected. In an object, the key gets null; in an array, a ',' where a
+    value is missing stands for null (as in JavaScript), while an array that
+    ends there just ends.
+    */
+    template<typename SAX>
+    bool recover_missing_value(SAX* sax, const std::vector<std::uint8_t>& states, std::true_type /*allow_recovery*/)
+    {
+        JSON_ASSERT(!states.empty());
+        if (states.back() == 0 || last_token == token_type::value_separator)
+        {
+            return sax->null();
+        }
+        return true;
+    }
+
+    /// recover from a missing key; last_token is where it was expected
+    template<typename SAX>
+    next_step recover_key(SAX* sax)
+    {
+        switch (last_token)
+        {
+            case token_type::value_separator:
+            case token_type::end_object:
+            case token_type::end_array:
+            case token_type::end_of_input:
+                // no member: the object's state handles the token
+                return next_step::evaluate_state;
+
+            case token_type::parse_error:
+                recover_token();
+                if (last_token == token_type::value_string)
+                {
+                    // a key that could be repaired
+                    return parse_key(sax);
+                }
+                skip_member();
+                return next_step::evaluate_state;
+
+            case token_type::uninitialized:
+            case token_type::literal_true:
+            case token_type::literal_false:
+            case token_type::literal_null:
+            case token_type::value_string:
+            case token_type::value_unsigned:
+            case token_type::value_integer:
+            case token_type::value_float:
+            case token_type::begin_array:
+            case token_type::begin_object:
+            case token_type::name_separator:
+            case token_type::literal_or_value:
+            default:
+                // a member without a key
+                skip_member();
+                return next_step::evaluate_state;
+        }
+    }
+
+    /// recover from a missing name separator (:) after the key; last_token
+    /// is where it was expected
+    template<typename SAX>
+    next_step recover_name_separator(SAX* sax)
+    {
+        switch (last_token)
+        {
+            case token_type::value_separator:
+            case token_type::end_object:
+            case token_type::end_array:
+            case token_type::end_of_input:
+                // the value is missing as well
+                return sax->null() ? next_step::evaluate_state : next_step::stop;
+
+            case token_type::uninitialized:
+            case token_type::literal_true:
+            case token_type::literal_false:
+            case token_type::literal_null:
+            case token_type::value_string:
+            case token_type::value_unsigned:
+            case token_type::value_integer:
+            case token_type::value_float:
+            case token_type::begin_array:
+            case token_type::begin_object:
+            case token_type::name_separator:
+            case token_type::parse_error:
+            case token_type::literal_or_value:
+            default:
+                // a missing ':'; the value begins here
+                return next_step::parse_value;
+        }
+    }
+
+    /// recover from a token after an object member that is neither ',' nor
+    /// '}' (nor ']' or the end of the input, which the caller handles)
+    template<typename SAX>
+    next_step recover_member(SAX* sax, std::true_type /*allow_recovery*/)
+    {
+        if (last_token == token_type::parse_error)
+        {
+            recover_token();
+        }
+        if (last_token == token_type::value_string)
+        {
+            // a missing ','; the next key begins here
+            return parse_key(sax);
+        }
+        skip_member();
+        return next_step::evaluate_state;
+    }
+
+    /// the parser for parse() and accept() never recovers (and does not come
+    /// here, as report_error() returned false)
+    template<typename SAX>
+    JSON_INTERNAL_ALWAYS_INLINE
+    std::false_type recover_member(SAX* /*sax*/, std::false_type /*allow_recovery*/) const noexcept
+    {
+        return {};
+    }
+
     /// get next token from lexer
     token_type get_token()
     {
@@ -612,6 +1320,12 @@ class parser
     const bool allow_exceptions = true;
     /// whether trailing commas in objects and arrays should be ignored (true) or signaled as errors (false)
     const bool ignore_trailing_commas = false;
+    /// whether an error was reported to the SAX parser
+    bool error_reported = false;
+    /// the position of the last reported error
+    std::size_t last_error_position = 0;
+    /// the token of the last reported error
+    token_type last_error_token = token_type::uninitialized;
 };
 
 }  // namespace detail

include/nlohmann/detail/macro_scope.hpp

@@ -215,6 +215,17 @@
     #define JSON_NO_UNIQUE_ADDRESS
 #endif
 
+// Inlines small functions even in unoptimized builds, so that they are not
+// emitted. The parsers for parse(), accept(), and from_*() use it for the
+// functions that stand in for the code recovering from errors (see #3989).
+// MSVC is left to decide, as it warns (C4714) where it does not inline a
+// __forceinline function.
+#if defined(_MSC_VER) && !defined(__clang__)
+    #define JSON_INTERNAL_ALWAYS_INLINE
+#else
+    #define JSON_INTERNAL_ALWAYS_INLINE JSON_HEDLEY_ALWAYS_INLINE
+#endif
+
 // Clang targeting MinGW does not survive the thread_local storage the copy
 // constructor uses to bound its descent: every test that copies a value
 // segfaults with clang 11.0.1 and clang 18.1.8, while the same tests pass with

include/nlohmann/detail/macro_unscope.hpp

@@ -19,6 +19,7 @@
 #undef NLOHMANN_CAN_CALL_STD_FUNC_IMPL
 #undef JSON_INLINE_VARIABLE
 #undef JSON_NO_UNIQUE_ADDRESS
+#undef JSON_INTERNAL_ALWAYS_INLINE
 #undef JSON_DISABLE_ENUM_SERIALIZATION
 #undef JSON_DISABLE_TUPLE_REFERENCE_CONVERSION
 #undef JSON_UNLOCKED_FILE_IO

include/nlohmann/detail/string_utils.hpp

@@ -13,6 +13,7 @@
 #include <cstddef> // size_t
 #include <cstdint> // uint8_t, uint32_t
 #include <string> // string, to_string
+#include <utility> // move
 
 #include <nlohmann/detail/abi_macros.hpp>
 #include <nlohmann/detail/macro_scope.hpp>

include/nlohmann/detail/view/errors.hpp

@@ -144,11 +144,21 @@ struct throwing_sax
 
     /// (a template, as in json_sax_dom_parser: the parser passes the concrete
     /// exception type, which is thrown as is)
+    ///
+    /// It is not [[noreturn]]: sax_parse() recovers from an error if
+    /// parse_error() returns true, and MSVC reports that code as unreachable
+    /// (C4702) for a handler that never returns. The flag hides that from it.
     template<class Exception>
-    [[noreturn]] bool parse_error(std::size_t /*unused*/, const std::string& /*unused*/, const Exception& ex)
+    bool parse_error(std::size_t /*unused*/, const std::string& /*unused*/, const Exception& ex)
     {
-        NLOHMANN_VIEW_THROW(ex);
+        if (throwing)
+        {
+            NLOHMANN_VIEW_THROW(ex);
+        }
+        return false; // LCOV_EXCL_LINE
     }
+
+    bool throwing = true;
 };
 
 /*!

include/nlohmann/json.hpp

@@ -157,7 +157,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
     friend class ::nlohmann::detail::iter_impl;
     template<typename BasicJsonType, typename CharType, typename OutputSinkType>
     friend class ::nlohmann::detail::binary_writer;
-    template<typename BasicJsonType, typename InputType, typename SAX>
+    template<typename BasicJsonType, typename InputType, typename SAX, bool AllowRecovery>
     friend class ::nlohmann::detail::binary_reader;
     template<typename BasicJsonType, typename InputAdapterType, bool Collect>
     friend class ::nlohmann::detail::json_sax_dom_parser;
@@ -3133,7 +3133,8 @@ public:
         {
             return parser(std::move(ia), nullptr, true, ignore_comments, ignore_trailing_commas).sax_parse(sax, strict);
         }
-        return detail::binary_reader<basic_json, InputAdapterType, SAX>(std::move(ia), format).sax_parse(sax, strict, tag_handler);
+        // the SAX parser may recover from errors (see parse_error())
+        return detail::binary_reader<basic_json, InputAdapterType, SAX, true>(std::move(ia), format).sax_parse(sax, strict, tag_handler);
     }
 
     /// serialize @a j into a new vector; @a write receives the vector-backed writer

single_include/nlohmann/json_view.hpp

@@ -2938,11 +2938,21 @@ struct throwing_sax
 
     /// (a template, as in json_sax_dom_parser: the parser passes the concrete
     /// exception type, which is thrown as is)
+    ///
+    /// It is not [[noreturn]]: sax_parse() recovers from an error if
+    /// parse_error() returns true, and MSVC reports that code as unreachable
+    /// (C4702) for a handler that never returns. The flag hides that from it.
     template<class Exception>
-    [[noreturn]] bool parse_error(std::size_t /*unused*/, const std::string& /*unused*/, const Exception& ex)
+    bool parse_error(std::size_t /*unused*/, const std::string& /*unused*/, const Exception& ex)
     {
-        NLOHMANN_VIEW_THROW(ex);
+        if (throwing)
+        {
+            NLOHMANN_VIEW_THROW(ex);
+        }
+        return false; // LCOV_EXCL_LINE
     }
+
+    bool throwing = true;
 };
 
 /*!

tests/src/fuzzer-parse_bjdata.cpp

@@ -47,6 +47,10 @@ dumps is stable under exactly the same values that break operator==.
 The unit tests run the same checks on a fixed corpus (see the "BJData round-trip
 invariants" test case), so keep both in sync.
 
+Furthermore, it reads data with a SAX parser that recovers from every error
+and checks that the events are balanced, that reading ends, and that it
+reports an error exactly when from_bjdata() fails (see #3989).
+
 Finally, it reads the data from a stream, a non-contiguous iterator range, and
 a FILE*, which read byte by byte, and checks that each gives the same value or
 error (id, message, byte position) as the pointer range, which takes the bulk
@@ -57,6 +61,7 @@ drivers.
 */
 
 #include "fuzzer_common.hpp"
+#include "fuzzer-recovering_checker.hpp"
 
 namespace
 {
@@ -81,6 +86,9 @@ static bool is_value_stable(const json& lhs, const json& rhs)
 // see http://llvm.org/docs/LibFuzzer.html
 extern "C" int LLVMFuzzerTestOneInput(const uint8_t* data, size_t size)
 {
+    // recover from all errors, reading from memory and from a stream
+    const bool recovered_without_errors = check_recovering_parse(data, size, json::input_format_t::bjdata).errors == 0;
+
     std::vector<uint8_t> const vec1(data, data + size);
 
     // step 0: parse input without exceptions
@@ -99,6 +107,9 @@ extern "C" int LLVMFuzzerTestOneInput(const uint8_t* data, size_t size)
         // without exceptions, the same input must give the same value
         assert(!noexcept_threw && !j_noexcept.is_discarded() && same_value(j_noexcept, j1));
 
+        // the recovering parser must not have reported an error either
+        assert(recovered_without_errors);
+
         try
         {
             // step 2.1: round trip without adding size annotations to container types
@@ -132,6 +143,7 @@ extern "C" int LLVMFuzzerTestOneInput(const uint8_t* data, size_t size)
     {
         // parse errors are ok, because input may be random bytes
         assert(parsed || noexcept_threw || j_noexcept.is_discarded());
+        assert(parsed || !recovered_without_errors);
     }
     catch (const json::type_error&)
     {
@@ -142,6 +154,7 @@ extern "C" int LLVMFuzzerTestOneInput(const uint8_t* data, size_t size)
     {
         // out of range errors may happen if provided sizes are excessive
         assert(parsed || noexcept_threw || j_noexcept.is_discarded());
+        assert(parsed || !recovered_without_errors);
     }
 
     // step 3: the other input adapters must read the data alike

tests/src/fuzzer-parse_bon8.cpp

@@ -17,6 +17,10 @@ array data, it performs the following steps:
 - j2 = from_bon8(vec)
 - assert(to_bon8(j2) == vec)
 
+Furthermore, it reads data with a SAX parser that recovers from every error
+and checks that the events are balanced, that reading ends, and that it
+reports an error exactly when from_bon8() fails (see #3989).
+
 Finally, it reads the data from a stream, a non-contiguous iterator range, and
 a FILE*, which read byte by byte, and checks that each gives the same value or
 error (id, message, byte position) as the pointer range, which takes the bulk
@@ -27,6 +31,7 @@ drivers.
 */
 
 #include "fuzzer_common.hpp"
+#include "fuzzer-recovering_checker.hpp"
 
 namespace
 {
@@ -44,6 +49,9 @@ struct read_bon8
 // see http://llvm.org/docs/LibFuzzer.html
 extern "C" int LLVMFuzzerTestOneInput(const uint8_t* data, size_t size)
 {
+    // recover from all errors, reading from memory and from a stream
+    const bool recovered_without_errors = check_recovering_parse(data, size, json::input_format_t::bon8).errors == 0;
+
     std::vector<uint8_t> const vec1(data, data + size);
 
     // step 0: parse input without exceptions
@@ -62,6 +70,9 @@ extern "C" int LLVMFuzzerTestOneInput(const uint8_t* data, size_t size)
         // without exceptions, the same input must give the same value
         assert(!noexcept_threw && !j_noexcept.is_discarded() && same_value(j_noexcept, j1));
 
+        // the recovering parser must not have reported an error either
+        assert(recovered_without_errors);
+
         try
         {
             // step 2: round trip
@@ -83,6 +94,7 @@ extern "C" int LLVMFuzzerTestOneInput(const uint8_t* data, size_t size)
     {
         // parse errors are ok, because input may be random bytes
         assert(parsed || noexcept_threw || j_noexcept.is_discarded());
+        assert(parsed || !recovered_without_errors);
     }
     catch (const json::type_error&)
     {
@@ -93,6 +105,7 @@ extern "C" int LLVMFuzzerTestOneInput(const uint8_t* data, size_t size)
     {
         // out of range errors may happen if provided sizes are excessive
         assert(parsed || noexcept_threw || j_noexcept.is_discarded());
+        assert(parsed || !recovered_without_errors);
     }
 
     // step 3: the other input adapters must read the data alike

tests/src/fuzzer-parse_bson.cpp

@@ -17,6 +17,10 @@ array data, it performs the following steps:
 - j2 = from_bson(vec)
 - assert(to_bson(j2) == vec)
 
+Furthermore, it reads data with a SAX parser that recovers from every error
+and checks that the events are balanced, that reading ends, and that it
+reports an error exactly when from_bson() fails (see #3989).
+
 Finally, it reads the data from a stream, a non-contiguous iterator range, and
 a FILE*, which read byte by byte, and checks that each gives the same value or
 error (id, message, byte position) as the pointer range, which takes the bulk
@@ -27,6 +31,7 @@ drivers.
 */
 
 #include "fuzzer_common.hpp"
+#include "fuzzer-recovering_checker.hpp"
 
 namespace
 {
@@ -44,6 +49,9 @@ struct read_bson
 // see http://llvm.org/docs/LibFuzzer.html
 extern "C" int LLVMFuzzerTestOneInput(const uint8_t* data, size_t size)
 {
+    // recover from all errors, reading from memory and from a stream
+    const bool recovered_without_errors = check_recovering_parse(data, size, json::input_format_t::bson).errors == 0;
+
     std::vector<uint8_t> const vec1(data, data + size);
 
     // step 0: parse input without exceptions
@@ -62,6 +70,9 @@ extern "C" int LLVMFuzzerTestOneInput(const uint8_t* data, size_t size)
         // without exceptions, the same input must give the same value
         assert(!noexcept_threw && !j_noexcept.is_discarded() && same_value(j_noexcept, j1));
 
+        // the recovering parser must not have reported an error either
+        assert(recovered_without_errors);
+
         try
         {
             // step 2: round trip
@@ -83,6 +94,7 @@ extern "C" int LLVMFuzzerTestOneInput(const uint8_t* data, size_t size)
     {
         // parse errors are ok, because input may be random bytes
         assert(parsed || noexcept_threw || j_noexcept.is_discarded());
+        assert(parsed || !recovered_without_errors);
     }
     catch (const json::type_error&)
     {
@@ -93,6 +105,7 @@ extern "C" int LLVMFuzzerTestOneInput(const uint8_t* data, size_t size)
     {
         // out of range errors can occur during parsing, too
         assert(parsed || noexcept_threw || j_noexcept.is_discarded());
+        assert(parsed || !recovered_without_errors);
     }
 
     // step 3: the other input adapters must read the data alike

tests/src/fuzzer-parse_cbor.cpp

@@ -17,6 +17,10 @@ array data, it performs the following steps:
 - j2 = from_cbor(vec)
 - assert(to_cbor(j2) == vec)
 
+Furthermore, it reads data with a SAX parser that recovers from every error
+and checks that the events are balanced, that reading ends, and that it
+reports an error exactly when from_cbor() fails (see #3989).
+
 Finally, it reads the data from a stream, a non-contiguous iterator range, and
 a FILE*, which read byte by byte, and checks that each gives the same value or
 error (id, message, byte position) as the pointer range, which takes the bulk
@@ -27,6 +31,7 @@ drivers.
 */
 
 #include "fuzzer_common.hpp"
+#include "fuzzer-recovering_checker.hpp"
 
 namespace
 {
@@ -44,6 +49,9 @@ struct read_cbor
 // see http://llvm.org/docs/LibFuzzer.html
 extern "C" int LLVMFuzzerTestOneInput(const uint8_t* data, size_t size)
 {
+    // recover from all errors, reading from memory and from a stream
+    const bool recovered_without_errors = check_recovering_parse(data, size, json::input_format_t::cbor).errors == 0;
+
     std::vector<uint8_t> const vec1(data, data + size);
 
     // step 0: parse input without exceptions
@@ -62,6 +70,9 @@ extern "C" int LLVMFuzzerTestOneInput(const uint8_t* data, size_t size)
         // without exceptions, the same input must give the same value
         assert(!noexcept_threw && !j_noexcept.is_discarded() && same_value(j_noexcept, j1));
 
+        // the recovering parser must not have reported an error either
+        assert(recovered_without_errors);
+
         try
         {
             // step 2: round trip
@@ -83,6 +94,7 @@ extern "C" int LLVMFuzzerTestOneInput(const uint8_t* data, size_t size)
     {
         // parse errors are ok, because input may be random bytes
         assert(parsed || noexcept_threw || j_noexcept.is_discarded());
+        assert(parsed || !recovered_without_errors);
     }
     catch (const json::type_error&)
     {
@@ -93,6 +105,7 @@ extern "C" int LLVMFuzzerTestOneInput(const uint8_t* data, size_t size)
     {
         // out of range errors can occur during parsing, too
         assert(parsed || noexcept_threw || j_noexcept.is_discarded());
+        assert(parsed || !recovered_without_errors);
     }
 
     // step 3: the other input adapters must read the data alike

tests/src/fuzzer-parse_json.cpp

@@ -24,11 +24,16 @@ array data, it performs the following steps:
 The pointer range takes the bulk fast paths, the other input adapters read byte
 by byte; see check_input_adapters().
 
+Furthermore, it parses data with a SAX parser that recovers from every error
+and checks that the events are balanced, that parsing ends, and that valid
+input is parsed without errors (see #3989).
+
 The provided function `LLVMFuzzerTestOneInput` can be used in different fuzzer
 drivers.
 */
 
 #include "fuzzer_common.hpp"
+#include "fuzzer-recovering_checker.hpp"
 
 namespace
 {
@@ -59,6 +64,13 @@ struct accept_json
 // see http://llvm.org/docs/LibFuzzer.html
 extern "C" int LLVMFuzzerTestOneInput(const uint8_t* data, size_t size)
 {
+    // recover from all errors, reading from memory and from a stream
+    {
+        const auto checker = check_recovering_parse(data, size, json::input_format_t::json);
+        assert(checker.events <= (4 * size) + 4);
+        assert((checker.errors == 0) == json::accept(data, data + size));
+    }
+
     // step 0: parse input without exceptions
     bool noexcept_threw = false;
     json const j_noexcept = parse_without_exceptions([&] { return json::parse(data, data + size, nullptr, false); }, noexcept_threw);

tests/src/fuzzer-parse_msgpack.cpp

@@ -17,6 +17,10 @@ array data, it performs the following steps:
 - j2 = from_msgpack(vec)
 - assert(to_msgpack(j2) == vec)
 
+Furthermore, it reads data with a SAX parser that recovers from every error
+and checks that the events are balanced, that reading ends, and that it
+reports an error exactly when from_msgpack() fails (see #3989).
+
 Finally, it reads the data from a stream, a non-contiguous iterator range, and
 a FILE*, which read byte by byte, and checks that each gives the same value or
 error (id, message, byte position) as the pointer range, which takes the bulk
@@ -27,6 +31,7 @@ drivers.
 */
 
 #include "fuzzer_common.hpp"
+#include "fuzzer-recovering_checker.hpp"
 
 namespace
 {
@@ -44,6 +49,9 @@ struct read_msgpack
 // see http://llvm.org/docs/LibFuzzer.html
 extern "C" int LLVMFuzzerTestOneInput(const uint8_t* data, size_t size)
 {
+    // recover from all errors, reading from memory and from a stream
+    const bool recovered_without_errors = check_recovering_parse(data, size, json::input_format_t::msgpack).errors == 0;
+
     std::vector<uint8_t> const vec1(data, data + size);
 
     // step 0: parse input without exceptions
@@ -62,6 +70,9 @@ extern "C" int LLVMFuzzerTestOneInput(const uint8_t* data, size_t size)
         // without exceptions, the same input must give the same value
         assert(!noexcept_threw && !j_noexcept.is_discarded() && same_value(j_noexcept, j1));
 
+        // the recovering parser must not have reported an error either
+        assert(recovered_without_errors);
+
         try
         {
             // step 2: round trip
@@ -83,6 +94,7 @@ extern "C" int LLVMFuzzerTestOneInput(const uint8_t* data, size_t size)
     {
         // parse errors are ok, because input may be random bytes
         assert(parsed || noexcept_threw || j_noexcept.is_discarded());
+        assert(parsed || !recovered_without_errors);
     }
     catch (const json::type_error&)
     {
@@ -93,6 +105,7 @@ extern "C" int LLVMFuzzerTestOneInput(const uint8_t* data, size_t size)
     {
         // out of range errors may happen if provided sizes are excessive
         assert(parsed || noexcept_threw || j_noexcept.is_discarded());
+        assert(parsed || !recovered_without_errors);
     }
 
     // step 3: the other input adapters must read the data alike

tests/src/fuzzer-parse_ubjson.cpp

@@ -26,6 +26,10 @@ array data, it performs the following steps:
 The unit tests run the same checks on a fixed corpus (see the "UBJSON round-trip
 invariants" test case), so keep both in sync.
 
+Furthermore, it reads data with a SAX parser that recovers from every error
+and checks that the events are balanced, that reading ends, and that it
+reports an error exactly when from_ubjson() fails (see #3989).
+
 Finally, it reads the data from a stream, a non-contiguous iterator range, and
 a FILE*, which read byte by byte, and checks that each gives the same value or
 error (id, message, byte position) as the pointer range, which takes the bulk
@@ -36,6 +40,7 @@ drivers.
 */
 
 #include "fuzzer_common.hpp"
+#include "fuzzer-recovering_checker.hpp"
 
 namespace
 {
@@ -53,6 +58,9 @@ struct read_ubjson
 // see http://llvm.org/docs/LibFuzzer.html
 extern "C" int LLVMFuzzerTestOneInput(const uint8_t* data, size_t size)
 {
+    // recover from all errors, reading from memory and from a stream
+    const bool recovered_without_errors = check_recovering_parse(data, size, json::input_format_t::ubjson).errors == 0;
+
     std::vector<uint8_t> const vec1(data, data + size);
 
     // step 0: parse input without exceptions
@@ -71,6 +79,9 @@ extern "C" int LLVMFuzzerTestOneInput(const uint8_t* data, size_t size)
         // without exceptions, the same input must give the same value
         assert(!noexcept_threw && !j_noexcept.is_discarded() && same_value(j_noexcept, j1));
 
+        // the recovering parser must not have reported an error either
+        assert(recovered_without_errors);
+
         try
         {
             // step 2.1: round trip without adding size annotations to container types
@@ -102,6 +113,7 @@ extern "C" int LLVMFuzzerTestOneInput(const uint8_t* data, size_t size)
     {
         // parse errors are ok, because input may be random bytes
         assert(parsed || noexcept_threw || j_noexcept.is_discarded());
+        assert(parsed || !recovered_without_errors);
     }
     catch (const json::type_error&)
     {
@@ -112,6 +124,7 @@ extern "C" int LLVMFuzzerTestOneInput(const uint8_t* data, size_t size)
     {
         // out of range errors may happen if provided sizes are excessive
         assert(parsed || noexcept_threw || j_noexcept.is_discarded());
+        assert(parsed || !recovered_without_errors);
     }
 
     // step 3: the other input adapters must read the data alike

tests/src/fuzzer-recovering_checker.hpp

@@ -0,0 +1,154 @@
+//     __ _____ _____ _____
+//  __|  |   __|     |   | |  JSON for Modern C++ (supporting code)
+// |  |  |__   |  |  | | | |  version 3.12.0
+// |_____|_____|_____|_|___|  https://github.com/nlohmann/json
+//
+// SPDX-FileCopyrightText: 2013-2026 Niels Lohmann <https://nlohmann.me>
+// SPDX-License-Identifier: MIT
+
+#pragma once
+
+#include <cassert>
+#include <cstddef>
+#include <cstdint>
+#include <sstream>
+#include <string>
+#include <vector>
+#include <nlohmann/json.hpp>
+
+namespace
+{
+// a SAX parser that recovers from every error and checks that the events are
+// balanced and that every key is followed by exactly one value
+class recovering_checker : public nlohmann::json_sax<nlohmann::json>
+{
+  public:
+    bool null() override
+    {
+        return value();
+    }
+
+    bool boolean(bool /*val*/) override
+    {
+        return value();
+    }
+
+    bool number_integer(number_integer_t /*val*/) override
+    {
+        return value();
+    }
+
+    bool number_unsigned(number_unsigned_t /*val*/) override
+    {
+        return value();
+    }
+
+    bool number_float(number_float_t /*val*/, const string_t& /*s*/) override
+    {
+        return value();
+    }
+
+    bool string(string_t& /*val*/) override
+    {
+        return value();
+    }
+
+    bool binary(binary_t& /*val*/) override
+    {
+        return value();
+    }
+
+    bool start_object(std::size_t /*elements*/) override
+    {
+        value();
+        stack.push_back('o');
+        return true;
+    }
+
+    bool key(string_t& /*val*/) override
+    {
+        ++events;
+        assert(!stack.empty() && stack.back() == 'o');
+        stack.back() = 'v';
+        return true;
+    }
+
+    bool end_object() override
+    {
+        ++events;
+        assert(!stack.empty() && stack.back() == 'o');
+        stack.pop_back();
+        return true;
+    }
+
+    bool start_array(std::size_t /*elements*/) override
+    {
+        value();
+        stack.push_back('a');
+        return true;
+    }
+
+    bool end_array() override
+    {
+        ++events;
+        assert(!stack.empty() && stack.back() == 'a');
+        stack.pop_back();
+        return true;
+    }
+
+    bool parse_error(std::size_t /*position*/, const std::string& /*last_token*/, const nlohmann::detail::exception& /*ex*/) override
+    {
+        ++errors;
+        return true;
+    }
+
+    bool complete() const
+    {
+        return stack.empty();
+    }
+
+    std::size_t events = 0;
+    std::size_t errors = 0;
+
+  private:
+    bool value()
+    {
+        ++events;
+        if (!stack.empty())
+        {
+            // an array element, or the value of a key
+            assert(stack.back() != 'o');
+            if (stack.back() == 'v')
+            {
+                stack.back() = 'o';
+            }
+        }
+        return true;
+    }
+
+    // 'a' for an array, 'o' for an object that expects a key, 'v' for an
+    // object that expects the value of a key
+    std::vector<char> stack {}; // NOLINT(readability-redundant-member-init)
+};
+
+/// parses @a data with a recovering_checker from memory and from a stream,
+/// checks that both see the same, that the events are balanced, and that the
+/// number of errors is bounded, and returns the checker (see #3989)
+inline recovering_checker check_recovering_parse(const std::uint8_t* data, const std::size_t size, const nlohmann::json::input_format_t format)
+{
+    recovering_checker checker;
+    const bool ok = nlohmann::json::sax_parse(data, data + size, &checker, format);
+    assert(checker.complete());
+    assert(checker.errors <= size + 1);
+    assert(ok == (checker.errors == 0));
+
+    std::istringstream stream(std::string(reinterpret_cast<const char*>(data), size));
+    recovering_checker stream_checker;
+    assert(nlohmann::json::sax_parse(stream, &stream_checker, format) == ok);
+    assert(stream_checker.complete());
+    assert(stream_checker.events == checker.events);
+    assert(stream_checker.errors == checker.errors);
+
+    return checker;
+}
+} // namespace

tests/src/sax_event_loggers.hpp

@@ -131,11 +131,13 @@ struct SaxEventLogger : public nlohmann::json_sax<nlohmann::json>
     {
         errored = true;
         events.push_back("parse_error(" + std::to_string(position) + ")");
-        return false;
+        return recover;
     }
 
     std::vector<std::string> events {}; // NOLINT(readability-redundant-member-init)
     bool errored = false;
+    /// whether parse_error() asks the parser to recover from the error (see #3989)
+    bool recover = false;
 };
 
 struct SaxEventLoggerExitAfterStartObject : public SaxEventLogger

tests/src/unit-alt-string.cpp

@@ -415,6 +415,46 @@ TEST_CASE("alternative string type")
         CHECK(j2.dump() == R"({"/foo/0":"bar","/foo/1":"baz"})");
     }
 
+    SECTION("error recovery")
+    {
+        // a SAX parser that recovers from every error (see #3989)
+        struct recovering_parser : nlohmann::detail::json_sax_dom_parser<alt_json>
+        {
+            explicit recovering_parser(alt_json& j)
+                : nlohmann::detail::json_sax_dom_parser<alt_json>(j, false)
+            {}
+
+            // sax_parse() calls the SAX parser's own parse_error(), so hiding
+            // the one of the base class is what recovering takes
+            // NOLINTNEXTLINE(bugprone-derived-method-shadowing-base-method)
+            bool parse_error(std::size_t /*unused*/, const std::string& /*unused*/, const nlohmann::detail::exception& /*unused*/)
+            {
+                ++errors;
+                return true;
+            }
+
+            std::size_t errors = 0;
+        };
+
+        alt_json j;
+        recovering_parser sax(j);
+        // not inside CHECK(): MSVC reads the escape in a stringized raw string
+        const std::string input = R"([1., "a\qb", tru, {"k" 2}])";
+        CHECK(!alt_json::sax_parse(input, &sax));
+        CHECK(sax.errors == 4);
+        CHECK(j.dump() == R"([1,"aqb",null,{"k":2}])");
+
+        // a UBJSON high-precision number, a CBOR key that is not a string
+        alt_json u;
+        recovering_parser ubjson_sax(u);
+        CHECK(!alt_json::sax_parse(std::vector<std::uint8_t> {'[', 'H', 'i', 2, '1', '.', ']'}, &ubjson_sax, alt_json::input_format_t::ubjson));
+        CHECK(u.dump() == "[1]");
+        alt_json c;
+        recovering_parser cbor_sax(c);
+        CHECK(!alt_json::sax_parse(std::vector<std::uint8_t> {0xA2, 0x01, 0x02, 0x61, 'a', 0x03}, &cbor_sax, alt_json::input_format_t::cbor));
+        CHECK(c.dump() == R"({"a":3})");
+    }
+
     SECTION("conversion between basic_json specializations (#2649)")
     {
         // explicit conversions are always possible

tests/src/unit-class_parser.cpp

@@ -2953,6 +2953,651 @@ TEST_CASE("diagnostic positions: value lifetime, input adapters, and SAX")
 }
 #endif
 
+namespace
+{
+/// builds a value like json::parse(), but asks the parser to recover from
+/// errors (see #3989), and checks that the events it receives are balanced
+class RecoveringDomParser
+{
+  public:
+    explicit RecoveringDomParser(json& j, std::size_t max_errors_ = static_cast<std::size_t>(-1))
+        : dom(j, false)
+        , max_errors(max_errors_)
+    {}
+
+    bool null()
+    {
+        value();
+        return dom.null();
+    }
+
+    bool boolean(bool val)
+    {
+        value();
+        return dom.boolean(val);
+    }
+
+    bool number_integer(json::number_integer_t val)
+    {
+        value();
+        return dom.number_integer(val);
+    }
+
+    bool number_unsigned(json::number_unsigned_t val)
+    {
+        value();
+        return dom.number_unsigned(val);
+    }
+
+    bool number_float(json::number_float_t val, const std::string& s)
+    {
+        value();
+        return dom.number_float(val, s);
+    }
+
+    bool string(std::string& val)
+    {
+        value();
+        return dom.string(val);
+    }
+
+    bool binary(json::binary_t& val)
+    {
+        value();
+        return dom.binary(val);
+    }
+
+    bool start_object(std::size_t elements)
+    {
+        value();
+        stack.push_back('o');
+        return dom.start_object(elements);
+    }
+
+    bool key(std::string& val)
+    {
+        ++events;
+        if (stack.empty() || stack.back() != 'o')
+        {
+            well_formed = false;
+            return false;
+        }
+        stack.back() = 'v';
+        return dom.key(val);
+    }
+
+    bool end_object()
+    {
+        ++events;
+        if (stack.empty() || stack.back() != 'o')
+        {
+            well_formed = false;
+            return false;
+        }
+        stack.pop_back();
+        return dom.end_object();
+    }
+
+    bool start_array(std::size_t elements)
+    {
+        value();
+        stack.push_back('a');
+        return dom.start_array(elements);
+    }
+
+    bool end_array()
+    {
+        ++events;
+        if (stack.empty() || stack.back() != 'a')
+        {
+            well_formed = false;
+            return false;
+        }
+        stack.pop_back();
+        return dom.end_array();
+    }
+
+    bool parse_error(std::size_t /*unused*/, const std::string& /*unused*/, const json::exception& ex)
+    {
+        errors.emplace_back(ex.what());
+        return errors.size() < max_errors;
+    }
+
+    /// whether the events were balanced and every key was followed by a value
+    bool balanced() const
+    {
+        return well_formed && stack.empty();
+    }
+
+    /// builds the value
+    nlohmann::detail::json_sax_dom_parser<json> dom;
+    std::vector<std::string> errors {}; // NOLINT(readability-redundant-member-init)
+    std::size_t events = 0;
+    /// the open containers: 'a' for an array, 'o' for an object that expects
+    /// a key, 'v' for an object that expects the value of a key
+    std::vector<char> stack {}; // NOLINT(readability-redundant-member-init)
+    bool well_formed = true;
+    std::size_t max_errors;
+
+  private:
+    /// a value is passed: it is an array element, or the value of a key
+    void value()
+    {
+        ++events;
+        if (!stack.empty())
+        {
+            if (stack.back() == 'v')
+            {
+                stack.back() = 'o';
+            }
+            else if (stack.back() == 'o')
+            {
+                // a value without a key
+                well_formed = false;
+            }
+        }
+    }
+
+};
+
+struct RecoveryResult
+{
+    json value;
+    std::vector<std::string> errors;
+    std::size_t events;
+    bool ok;
+    bool balanced;
+};
+
+template<typename InputType>
+RecoveryResult parse_recovering(InputType&& input, const bool strict = true,
+                                const bool ignore_comments = false, const bool ignore_trailing_commas = false)
+{
+    json j;
+    RecoveringDomParser sax(j);
+    const bool ok = json::sax_parse(std::forward<InputType>(input), &sax, json::input_format_t::json,
+                                    strict, ignore_comments, ignore_trailing_commas);
+    return {j, sax.errors, sax.events, ok, sax.balanced()};
+}
+
+/// stops after a number of events, but recovers from errors
+class RecoveringCountdown
+{
+  public:
+    explicit RecoveringCountdown(const int count)
+        : countdown(count)
+    {}
+
+    bool null()
+    {
+        return countdown.null();
+    }
+
+    bool boolean(bool val)
+    {
+        return countdown.boolean(val);
+    }
+
+    bool number_integer(json::number_integer_t val)
+    {
+        return countdown.number_integer(val);
+    }
+
+    bool number_unsigned(json::number_unsigned_t val)
+    {
+        return countdown.number_unsigned(val);
+    }
+
+    bool number_float(json::number_float_t val, const std::string& s)
+    {
+        return countdown.number_float(val, s);
+    }
+
+    bool string(std::string& val)
+    {
+        return countdown.string(val);
+    }
+
+    bool binary(json::binary_t& val)
+    {
+        return countdown.binary(val);
+    }
+
+    bool start_object(std::size_t elements)
+    {
+        return countdown.start_object(elements);
+    }
+
+    bool key(std::string& val)
+    {
+        return countdown.key(val);
+    }
+
+    bool end_object()
+    {
+        return countdown.end_object();
+    }
+
+    bool start_array(std::size_t elements)
+    {
+        return countdown.start_array(elements);
+    }
+
+    bool end_array()
+    {
+        return countdown.end_array();
+    }
+
+    bool parse_error(std::size_t /*position*/, const std::string& /*last_token*/, const json::exception& /*ex*/) // NOLINT(readability-convert-member-functions-to-static)
+    {
+        return true;
+    }
+
+  private:
+    SaxCountdown countdown;
+};
+
+/// a repaired input: the value it is repaired to, and the number of errors
+struct Repair
+{
+    const char* input;
+    const char* expected;
+    std::size_t errors;
+};
+} // namespace
+
+TEST_CASE("parser error recovery (#3989)")
+{
+    SECTION("repairs")
+    {
+        const std::vector<Repair> repairs =
+        {
+            // a missing separator is inserted
+            {"[1 2]", "[1,2]", 1},
+            {R"({"a":1 "b":2})", R"({"a":1,"b":2})", 1},
+            {R"({"a" 1})", R"({"a":1})", 1},
+            {"[1 tru 2]", "[1,null,2]", 2},
+            {R"({"a" "b": 1})", R"({"a":"b"})", 2},
+
+            // a missing value is null in an object; in an array, a ',' stands
+            // for null, while an array that ends there just ends
+            {R"({"a":})", R"({"a":null})", 1},
+            {R"({"a"})", R"({"a":null})", 1},
+            {R"({"a","b":1})", R"({"a":null,"b":1})", 1},
+            {"[1,,2]", "[1,null,2]", 1},
+            {"[,1]", "[null,1]", 1},
+            {"[1,]", "[1]", 1},
+            {"[1,2,3,]", "[1,2,3]", 1},
+            {R"({"a":1,})", R"({"a":1})", 1},
+
+            // a broken string keeps what can be read
+            {R"(["a\qb"])", R"(["aqb"])", 1},
+            {R"({"na\me":1})", R"({"name":1})", 1},
+            {"[\"\xFF\"]", R"(["\uFFFD"])", 1},
+            {"[\"a\xC3(\"]", R"(["a\uFFFD("])", 1},
+            {"[\"\xE2\x82\"]", R"(["\uFFFD"])", 1},
+            {"[\"\xC3\\\\\", 1]", R"(["\uFFFD\\",1])", 1},
+            {R"(["\u12"])", R"(["\uFFFD"])", 1},
+            {R"(["\u12G4"])", R"(["\uFFFDG4"])", 1},
+            {R"(["\uDC00x"])", R"(["\uFFFDx"])", 1},
+            {R"(["\uD800x"])", R"(["\uFFFDx"])", 1},
+            {R"(["\uD800\u0041"])", R"(["\uFFFDA"])", 1},
+            {R"(["\uD800\uD800\uDC00"])", R"(["\uFFFD\uD800\uDC00"])", 1},
+            {R"(["\uD800\uD800\uD800x"])", R"(["\uFFFD\uFFFD\uFFFDx"])", 1},
+            {
+                R"(["\uD800\"x", 1])", R"(["\uFFFD\"x",1])", 1
+            },
+            {R"(["\uD800\q"])", R"(["\uFFFDq"])", 1},
+            {"[\"a\tb\"]", R"(["a\tb"])", 1},
+            {R"(["a\qb\u0041\x"])", R"(["aqbAx"])", 1},
+
+            // a broken number keeps its longest valid prefix
+            {"[1.]", "[1]", 1},
+            {"[-2.]", "[-2]", 1},
+            {"[1.5e]", "[1.5]", 1},
+            {"[1e+]", "[1]", 1},
+            {"[1.x2, 3]", "[1,3]", 1},
+
+            // what cannot be read at all is null
+            {"[1,NaN,3]", "[1,null,3]", 1},
+            {"[tru]", "[null]", 1},
+            {"[-]", "[null]", 1},
+            {R"({"a":Infinity})", R"({"a":null})", 1},
+
+            // a stray token is dropped
+            {"[:1]", "[1]", 1},
+            {R"(["a":1])", R"(["a",1])", 1},
+            {R"({"a"::1})", R"({"a":1})", 1},
+
+            // a member that cannot be read is skipped
+            {R"({1:2,"b":3})", R"({"b":3})", 1},
+            {R"({"a":1 2})", R"({"a":1})", 1},
+            {R"({,"a":1})", R"({"a":1})", 1},
+            {R"({"a":1,,"b":2})", R"({"a":1,"b":2})", 1},
+            {"{a:1}", "{}", 1},
+            {R"({"a":1 [1,{"b":2}], "c":3})", R"({"a":1,"c":3})", 1},
+            {R"([{1}, "a"])", R"([{},"a"])", 1},
+
+            // a wrong closing bracket closes the innermost container
+            {R"({"a":[1,2}, "b":3})", R"({"a":[1,2],"b":3})", 1},
+            {R"([{"a":1], 2])", R"([{"a":1},2])", 1},
+            {"{]", "{}", 1},
+            {"[}", "[]", 1},
+
+            // the end of the input closes all containers
+            {R"({"a":[1,2)", R"({"a":[1,2]})", 1},
+            {"[", "[]", 1},
+            {"{", "{}", 1},
+            {R"({"a")", R"({"a":null})", 1},
+            {R"({"a":)", R"({"a":null})", 1},
+            {"[1,", "[1]", 1},
+            {"[[[1", "[[[1]]]", 1},
+            {
+                R"(["abc)", R"(["abc"])", 2
+            },
+            {"[1,tr", "[1,null]", 2},
+            {"\"abc", "\"abc\"", 1},
+            {"[\"ab\ncd\"]", R"(["ab",null,"]"])", 4},
+
+            // what comes before the top-level value is skipped
+            {")]}'\n{\"a\":1}", R"({"a":1})", 1},
+            {R"(data: {"a":1})", R"({"a":1})", 1},
+            {"\xEF\xBB[1]", "[1]", 1},
+
+            // what comes after it is an error that ends parsing
+            {R"({"a":1}})", R"({"a":1})", 1},
+            {"[1}]", "[1]", 2},
+            {"[1] [2]", "[1]", 1},
+        };
+
+        for (const auto& repair : repairs)
+        {
+            CAPTURE(repair.input)
+            const auto result = parse_recovering(std::string(repair.input));
+            CHECK(!result.ok);
+            CHECK(result.balanced);
+            CHECK(result.value == json::parse(repair.expected));
+            CHECK(result.errors.size() == repair.errors);
+        }
+    }
+
+    SECTION("number overflow")
+    {
+        const auto result = parse_recovering(std::string("[1e999,-1e999]"));
+        CHECK(!result.ok);
+        CHECK(result.balanced);
+        CHECK(result.errors.size() == 2);
+        CHECK(result.errors[0] == "[json.exception.out_of_range.406] number overflow parsing '1e999'");
+        REQUIRE(result.value.size() == 2);
+        CHECK(result.value[0].is_number_float());
+        CHECK(result.value[0].get<double>() == std::numeric_limits<double>::infinity());
+        CHECK(result.value[1].get<double>() == -std::numeric_limits<double>::infinity());
+
+        // the SAX parser gets the number's text
+        SaxEventLogger logger;
+        logger.recover = true;
+        CHECK(!json::sax_parse("1e999", &logger));
+        CHECK(logger.events == std::vector<std::string>({"parse_error(5)", "number_float(1e999)"}));
+    }
+
+    SECTION("nothing to recover")
+    {
+        for (const std::string s :
+                {
+                    "", "   ", "]", "tru", "NaN", ",:", "/* comment"
+                })
+        {
+            CAPTURE(s)
+            const auto result = parse_recovering(s, true, true);
+            CHECK(!result.ok);
+            CHECK(result.balanced);
+            CHECK(result.events == 0);
+            CHECK(result.value == nullptr);
+            CHECK(result.errors.size() == 1);
+        }
+    }
+
+    SECTION("error messages")
+    {
+        // the first error is reported as without recovery
+        for (const std::string s :
+                {
+                    "[1 2]", R"({"a":1 "b":2})", R"({"a" 1})", R"({"a":})", "[1,]", "[1.]",
+                    R"(["a\qb"])", "[1e999]", "{1:2}", R"({"a":[1,2}})", "[1,", "[1] [2]", "{a:1}"
+                })
+        {
+            CAPTURE(s)
+            const auto result = parse_recovering(s);
+            REQUIRE(!result.errors.empty());
+            json _;
+            CHECK_THROWS_WITH_STD_STR(_ = json::parse(s), result.errors.front());
+        }
+
+        // the token of an error begins where the previous error was
+        const auto result = parse_recovering(std::string("[tru, fals, nul]"));
+        CHECK(result.errors == std::vector<std::string>(
+        {
+            "[json.exception.parse_error.101] parse error at line 1, column 5: syntax error while parsing value - invalid literal; last read: '[tru,'",
+            "[json.exception.parse_error.101] parse error at line 1, column 11: syntax error while parsing value - invalid literal; last read: ', fals,'",
+            "[json.exception.parse_error.101] parse error at line 1, column 16: syntax error while parsing value - invalid literal; last read: ', nul]'"
+        }));
+        CHECK(result.value == json::parse("[null,null,null]"));
+    }
+
+    SECTION("events")
+    {
+        // see #4522
+        SaxEventLogger logger;
+        logger.recover = true;
+        CHECK(!json::sax_parse(R"([{1}, "a"])", &logger));
+        CHECK(logger.events == std::vector<std::string>(
+        {
+            "start_array()", "start_object()", "parse_error(3)", "end_object()", "string(a)", "end_array()"
+        }));
+    }
+
+    SECTION("options")
+    {
+        SECTION("strict")
+        {
+            const auto result = parse_recovering(std::string("[1 2] [3]"), false);
+            CHECK(!result.ok);
+            CHECK(result.value == json::parse("[1,2]"));
+            CHECK(result.errors.size() == 1);
+        }
+
+        SECTION("ignore_trailing_commas")
+        {
+            for (const std::string s :
+                    {
+                        "[1,]", R"({"a":1,})", "[[1,],]"
+                    })
+            {
+                CAPTURE(s)
+                const auto result = parse_recovering(s, true, false, true);
+                CHECK(result.ok);
+                CHECK(result.errors.empty());
+            }
+
+            auto result = parse_recovering(std::string("[1,,]"), true, false, true);
+            CHECK(result.value == json::parse("[1,null]"));
+            CHECK(result.errors.size() == 1);
+
+            result = parse_recovering(std::string(R"({"a":1,,})"), true, false, true);
+            CHECK(result.value == json::parse(R"({"a":1})"));
+            CHECK(result.errors.size() == 1);
+        }
+
+        SECTION("ignore_comments")
+        {
+            auto result = parse_recovering(std::string("[1 /* one */ 2]"), true, true);
+            CHECK(result.value == json::parse("[1,2]"));
+            CHECK(result.errors.size() == 1);
+
+            // a comment that is not closed runs to the end of the input, which
+            // is not reported again
+            result = parse_recovering(std::string("[1, 2 /* unterminated"), true, true);
+            CHECK(result.balanced);
+            CHECK(result.value == json::parse("[1,2]"));
+            CHECK(result.errors.size() == 1);
+
+            // a '/' that does not begin a comment is garbage
+            result = parse_recovering(std::string("[1, /x, 2]"), true, true);
+            CHECK(result.balanced);
+            CHECK(result.value == json::parse("[1,null,2]"));
+            CHECK(result.errors.size() == 1);
+        }
+    }
+
+    SECTION("null bytes")
+    {
+        // a null byte ends the input, unless JSON_STRICT_NUL_HANDLING is set
+        const auto result = parse_recovering(std::string("[1,\0x", 5));
+        CHECK(result.balanced);
+        CHECK(!result.ok);
+#ifdef JSON_TEST_STRICT_NUL_HANDLING_ENABLED
+        CHECK(result.value == json::parse("[1,null]"));
+#else
+        CHECK(result.value == json::parse("[1]"));
+        CHECK(result.errors.size() == 1);
+#endif
+
+        const auto in_string = parse_recovering(std::string("[\"a\0b\"]", 7));
+        CHECK(in_string.balanced);
+#ifdef JSON_TEST_STRICT_NUL_HANDLING_ENABLED
+        CHECK(in_string.value == json::array({std::string("a\0b", 3)}));
+#else
+        CHECK(in_string.value == json::parse(R"(["a"])"));
+#endif
+    }
+
+    SECTION("the SAX parser stops recovering")
+    {
+        json j;
+        RecoveringDomParser sax(j, 2);
+        CHECK(!json::sax_parse("[1 2 3 4 5]", &sax));
+        CHECK(sax.errors.size() == 2);
+
+        // an error at a delimiter that an invalid token consumed is reported
+        // to the SAX parser, too
+        json j2;
+        RecoveringDomParser sax2(j2, 2);
+        CHECK(!json::sax_parse("[tru}, 1]", &sax2));
+        CHECK(sax2.errors.size() == 2);
+    }
+
+    SECTION("an event stops parsing during a repair")
+    {
+        // start_object() and key() are passed, then null() for the missing
+        // value returns false
+        RecoveringCountdown countdown(2);
+        CHECK(!json::sax_parse(R"({"a":})", &countdown));
+
+        // the end of the input: end_array() for the second array returns false
+        RecoveringCountdown countdown2(4);
+        CHECK(!json::sax_parse("[[1", &countdown2));
+    }
+
+    SECTION("input adapters")
+    {
+        // the lexer reads contiguous and streaming input differently, and it
+        // puts back a character that ended an invalid token
+        for (const std::string s :
+                {
+                    "[1 2]", "[tru}, 1]", R"({"a" "b\q", "c":[1.x, 2}})", "[\"\xFF\xC3(\", -, 1e+]", "{a:1,\"b\":2", ")]}' [1]"
+                })
+        {
+            CAPTURE(s)
+            const auto reference = parse_recovering(s);
+            CHECK(reference.balanced);
+
+            const auto from_c_string = parse_recovering(s.c_str());
+            CHECK(from_c_string.value == reference.value);
+            CHECK(from_c_string.errors == reference.errors);
+
+            const std::list<char> l(s.begin(), s.end());
+            json j;
+            RecoveringDomParser sax(j);
+            CHECK(!json::sax_parse(l.begin(), l.end(), &sax));
+            CHECK(j == reference.value);
+            CHECK(sax.errors == reference.errors);
+
+            std::istringstream ss(s);
+            const auto from_stream = parse_recovering(ss);
+            CHECK(from_stream.value == reference.value);
+            CHECK(from_stream.errors == reference.errors);
+        }
+    }
+
+    SECTION("long runs of errors")
+    {
+        // no error may copy all the input read before it
+        const auto closing = parse_recovering("[" + std::string(100000, '}'));
+        CHECK(closing.balanced);
+        CHECK(closing.value == json::array());
+
+        const auto garbage = parse_recovering("[" + std::string(100000, 'x') + "]");
+        CHECK(garbage.balanced);
+        CHECK(garbage.errors.size() == 1);
+
+        const auto commas = parse_recovering("{" + std::string(100000, ',') + "}");
+        CHECK(commas.balanced);
+        CHECK(commas.value == json::object());
+    }
+
+    SECTION("mutations of valid input")
+    {
+        // whatever the input, the events are balanced, every error is reported
+        // at most once, and valid input is parsed as usual
+        const std::vector<std::string> documents =
+        {
+            R"({"name": "value", "list": [1, -2.5, true, null, {"x": [[]]}], "e": "\u00e9"})",
+            R"([{"a": [1, 2, {"b": "c"}]}, [], {}, "\ud83d\ude00", 1e10])",
+            "{\"\xC3\xA9\": \"\xF0\x9F\x98\x80\"}",
+            R"(  {"k" : [ "v" , 0 ] }  )",
+        };
+        // each character that can be inserted, including a null byte
+        const std::string insertions("[]{},:\"x\\\0\xFF", 11);
+
+        std::vector<std::string> inputs;
+        for (const auto& doc : documents)
+        {
+            for (std::size_t i = 0; i <= doc.size(); ++i)
+            {
+                inputs.push_back(doc.substr(0, i));
+                if (i < doc.size())
+                {
+                    inputs.push_back(doc.substr(0, i) + doc.substr(i + 1));
+                }
+                for (const char c : insertions)
+                {
+                    inputs.push_back(doc.substr(0, i) + c + doc.substr(i));
+                }
+            }
+        }
+
+        for (const auto& s : inputs)
+        {
+            CAPTURE(s)
+            const auto result = parse_recovering(s);
+            CHECK(result.balanced);
+            CHECK(result.errors.size() <= s.size() + 1);
+            CHECK(result.events <= (4 * s.size()) + 4);
+            if (json::accept(s))
+            {
+                CHECK(result.ok);
+                CHECK(result.errors.empty());
+                CHECK(result.value == json::parse(s));
+            }
+            else
+            {
+                CHECK(!result.ok);
+                CHECK(!result.errors.empty());
+            }
+        }
+    }
+}
+
 TEST_CASE("accept() agrees with parse() on floats around the overflow limit")
 {
     // accept() does not convert a float that cannot overflow; the tokens

tests/src/unit-msgpack.cpp

@@ -31,8 +31,6 @@ using nlohmann::json;
 #include "make_test_data_available.hpp"
 #include "round_trip_corpus.hpp"
 #include "test_utils.hpp"
-#include "sax_countdown.hpp"
-using utils::SaxCountdown;
 
 
 TEST_CASE("MessagePack")
@@ -1645,30 +1643,6 @@ TEST_CASE("MessagePack")
             }
         }
     }
-
-    SECTION("SAX aborts")
-    {
-        SECTION("start_array(len)")
-        {
-            std::vector<uint8_t> const v = {0x93, 0x01, 0x02, 0x03};
-            SaxCountdown scp(0);
-            CHECK(!json::sax_parse(v, &scp, json::input_format_t::msgpack));
-        }
-
-        SECTION("start_object(len)")
-        {
-            std::vector<uint8_t> const v = {0x81, 0xa3, 0x66, 0x6F, 0x6F, 0xc2};
-            SaxCountdown scp(0);
-            CHECK(!json::sax_parse(v, &scp, json::input_format_t::msgpack));
-        }
-
-        SECTION("key()")
-        {
-            std::vector<uint8_t> const v = {0x81, 0xa3, 0x66, 0x6F, 0x6F, 0xc2};
-            SaxCountdown scp(1);
-            CHECK(!json::sax_parse(v, &scp, json::input_format_t::msgpack));
-        }
-    }
 }
 
 TEST_CASE("issue #5405 - array reserve for definite-length MessagePack arrays")
@@ -1739,21 +1713,6 @@ TEST_CASE("issue #5405 - array reserve for definite-length MessagePack arrays")
             CHECK(json::from_msgpack(packed) == j);
         }
     }
-
-    SECTION("a user-defined SAX consumer is unaffected by the internal DOM reserve optimization")
-    {
-        // the reserve() call is local to json_sax_dom_parser / json_sax_dom_callback_parser;
-        // a custom SAX consumer that does not touch a DOM array sees identical events
-        json j = json::array();
-        for (int i = 0; i < 100; ++i)
-        {
-            j.push_back(i);
-        }
-        const auto packed = json::to_msgpack(j);
-
-        SaxCountdown scp(1000000); // large enough to never trigger an abort
-        CHECK(json::sax_parse(packed, &scp, json::input_format_t::msgpack));
-    }
 }
 
 TEST_CASE("regression test - MessagePack ext type rejects a subtype that doesn't fit a single byte")
@@ -1792,15 +1751,6 @@ TEST_CASE("MessagePack nesting does not consume the call stack")
         CHECK(json::from_msgpack(input, true, false).is_discarded());
     }
 
-    SECTION("a well-formed deep value is read through the SAX interface")
-    {
-        std::vector<uint8_t> input(300000, 0x91);
-        input.push_back(0x01); // innermost value
-
-        SaxCountdown accept_all(600001);
-        CHECK(json::sax_parse(input, &accept_all, json::input_format_t::msgpack));
-    }
-
     SECTION("a well-formed deep value is read into a value")
     {
         const std::size_t depth = 10000;
@@ -1848,31 +1798,6 @@ TEST_CASE("MessagePack input that cannot be read is discarded by every overload"
 #endif
 }
 
-TEST_CASE("MessagePack SAX parsing stops at every event")
-{
-    // Containers are opened and closed by the loop that reads them; a SAX
-    // handler that rejects any event - including the end of a nested
-    // container - must stop the parse right there.
-    const auto count_events = [](const std::vector<std::uint8_t>& input)
-    {
-        int events = 0;
-        while (true)
-        {
-            SaxCountdown scp(events);
-            if (json::sax_parse(input, &scp, json::input_format_t::msgpack))
-            {
-                return events;
-            }
-            ++events;
-            REQUIRE(events < 1000);
-        }
-    };
-
-    // 20 events: every container kind closes inside another one
-    const json j = json::parse(R"({"a": [1, {"b": []}], "c": {"d": [[2]]}})");
-    CHECK(count_events(json::to_msgpack(j)) == 20);
-}
-
 TEST_CASE("single MessagePack roundtrip")
 {
     SECTION("sample.json")

tests/src/unit-regression3.cpp

@@ -22,14 +22,6 @@
 // scoped enum, so get<std::byte>() (needed below to get<std::vector<std::byte>>()
 // from a plain JSON array, not just from an already-binary value) relies on
 // enum serialization being enabled
-// capture whether JSON_DELETE_DEPRECATED_FUNCTIONS was enabled on the command
-// line *before* including json.hpp, since the library #undefs it once the header
-// has been fully processed (see include/nlohmann/detail/macro_unscope.hpp); the
-// tests of deprecated functions are skipped if these functions are deleted
-#if defined(JSON_DELETE_DEPRECATED_FUNCTIONS) && (JSON_DELETE_DEPRECATED_FUNCTIONS == 1)
-    #define JSON_TEST_DEPRECATED_FUNCTIONS_DELETED
-#endif
-
 #if defined(JSON_DISABLE_ENUM_SERIALIZATION) && (JSON_DISABLE_ENUM_SERIALIZATION == 1)
     #define SKIP_TESTS_FOR_ENUM_SERIALIZATION
 #endif
@@ -810,50 +802,6 @@ TEST_CASE("issue #5338 - truncated CBOR tagged binary subtype is rejected")
     }
 }
 
-TEST_CASE("issue #5676 - SAX parsing of CBOR tags")
-{
-    const json expected = json::binary({1, 2, 3}, 42);
-    const auto cbor = json::to_cbor(expected);
-
-    nlohmann::detail::json_sax_acceptor<json> acceptor;
-    CHECK_FALSE(json::sax_parse(cbor, &acceptor, json::input_format_t::cbor));
-    CHECK_FALSE(json::sax_parse(cbor, &acceptor, json::input_format_t::cbor,
-                                true, false, false, json::cbor_tag_handler_t::error));
-
-    CHECK(json::sax_parse(cbor, &acceptor, json::input_format_t::cbor,
-                          true, false, false, json::cbor_tag_handler_t::ignore));
-
-    json parsed;
-    nlohmann::detail::json_sax_dom_parser<json, nlohmann::detail::string_input_adapter_type> sax(parsed);
-    CHECK(json::sax_parse(cbor, &sax, json::input_format_t::cbor,
-                          true, false, false, json::cbor_tag_handler_t::store));
-    CHECK(parsed == expected);
-
-    json iterator_parsed;
-    nlohmann::detail::json_sax_dom_parser<json, nlohmann::detail::string_input_adapter_type> iterator_sax(iterator_parsed);
-    CHECK(json::sax_parse(cbor.begin(), cbor.end(), &iterator_sax, json::input_format_t::cbor,
-                          true, false, false, json::cbor_tag_handler_t::store));
-    CHECK(iterator_parsed == expected);
-
-#ifndef JSON_TEST_DEPRECATED_FUNCTIONS_DELETED
-    json span_parsed;
-    nlohmann::detail::json_sax_dom_parser<json, nlohmann::detail::string_input_adapter_type> span_sax(span_parsed);
-    CHECK(json::sax_parse(nlohmann::detail::span_input_adapter(cbor.data(), cbor.size()), &span_sax,
-                          json::input_format_t::cbor, true, false, false, json::cbor_tag_handler_t::store));
-    CHECK(span_parsed == expected);
-#endif
-
-    const std::string text = "null";
-    CHECK(json::sax_parse(text, &acceptor, json::input_format_t::json,
-                          true, false, false, json::cbor_tag_handler_t::store));
-    CHECK(json::sax_parse(text.begin(), text.end(), &acceptor, json::input_format_t::json,
-                          true, false, false, json::cbor_tag_handler_t::store));
-#ifndef JSON_TEST_DEPRECATED_FUNCTIONS_DELETED
-    CHECK(json::sax_parse(nlohmann::detail::span_input_adapter(text.data(), text.size()), &acceptor,
-                          json::input_format_t::json, true, false, false, json::cbor_tag_handler_t::store));
-#endif
-}
-
 TEST_CASE("issue #5402 - update(merge_objects=true) overwrites a primitive with an object")
 {
     json t = {{"k", 1}};

tests/src/unit-sax_parse.cpp

@@ -0,0 +1,768 @@
+//     __ _____ _____ _____
+//  __|  |   __|     |   | |  JSON for Modern C++ (supporting code)
+// |  |  |__   |  |  | | | |  version 3.12.0
+// |_____|_____|_____|_|___|  https://github.com/nlohmann/json
+//
+// SPDX-FileCopyrightText: 2013-2026 Niels Lohmann <https://nlohmann.me>
+// SPDX-License-Identifier: MIT
+
+/////////////////////////////////////////////////////////////////////
+// Tests that call basic_json::sax_parse have a file of their own: every
+// sax_parse call instantiates the parser and binary reader that recover from
+// errors (see #3989), and in unit-regression2.cpp, unit-regression3.cpp, and
+// unit-msgpack.cpp this made the objects too large for the MinGW linker to
+// relocate (see #5511).
+/////////////////////////////////////////////////////////////////////
+
+#include "doctest_compatibility.h"
+
+// capture whether JSON_DELETE_DEPRECATED_FUNCTIONS was enabled on the command
+// line *before* including json.hpp, since the library #undefs it once the header
+// has been fully processed (see include/nlohmann/detail/macro_unscope.hpp); the
+// tests of deprecated functions are skipped if these functions are deleted
+#if defined(JSON_DELETE_DEPRECATED_FUNCTIONS) && (JSON_DELETE_DEPRECATED_FUNCTIONS == 1)
+    #define JSON_TEST_DEPRECATED_FUNCTIONS_DELETED
+#endif
+
+#include <nlohmann/json.hpp>
+using json = nlohmann::json;
+
+#include <cmath>
+#include <cstddef>
+#include <cstdint>
+#include <initializer_list>
+#include <map>
+#include <string>
+#include <utility>
+#include <vector>
+
+#include "sax_countdown.hpp"
+using utils::SaxCountdown;
+
+// a narrow number_float_t, so that a double read from binary input can
+// overflow it
+using float_json = nlohmann::basic_json<std::map, std::vector, std::string, bool, std::int64_t, std::uint64_t, float>;
+
+DOCTEST_CLANG_SUPPRESS_WARNING_PUSH
+DOCTEST_CLANG_SUPPRESS_WARNING("-Wexit-time-destructors")
+
+namespace
+{
+/// builds a value from SAX events, asks the parser to recover from its first
+/// 100 errors, and checks that the events are balanced (see #3989)
+template<typename BasicJsonType>
+class BasicRecoveringParser
+{
+  public:
+    explicit BasicRecoveringParser(BasicJsonType& j)
+        : dom(j, false)
+    {}
+
+    bool null()
+    {
+        value();
+        return dom.null();
+    }
+
+    bool boolean(bool val)
+    {
+        value();
+        return dom.boolean(val);
+    }
+
+    bool number_integer(typename BasicJsonType::number_integer_t val)
+    {
+        value();
+        return dom.number_integer(val);
+    }
+
+    bool number_unsigned(typename BasicJsonType::number_unsigned_t val)
+    {
+        value();
+        return dom.number_unsigned(val);
+    }
+
+    bool number_float(typename BasicJsonType::number_float_t val, const std::string& s)
+    {
+        value();
+        return dom.number_float(val, s);
+    }
+
+    bool string(std::string& val)
+    {
+        value();
+        return dom.string(val);
+    }
+
+    bool binary(typename BasicJsonType::binary_t& val)
+    {
+        value();
+        return dom.binary(val);
+    }
+
+    bool start_object(std::size_t elements)
+    {
+        value();
+        stack.push_back('o');
+        return dom.start_object(elements);
+    }
+
+    bool key(std::string& val)
+    {
+        if (stack.empty() || stack.back() != 'o')
+        {
+            well_formed = false;
+            return false;
+        }
+        stack.back() = 'v';
+        return dom.key(val);
+    }
+
+    bool end_object()
+    {
+        if (stack.empty() || stack.back() != 'o')
+        {
+            well_formed = false;
+            return false;
+        }
+        stack.pop_back();
+        return dom.end_object();
+    }
+
+    bool start_array(std::size_t elements)
+    {
+        value();
+        stack.push_back('a');
+        return dom.start_array(elements);
+    }
+
+    bool end_array()
+    {
+        if (stack.empty() || stack.back() != 'a')
+        {
+            well_formed = false;
+            return false;
+        }
+        stack.pop_back();
+        return dom.end_array();
+    }
+
+    bool parse_error(std::size_t /*unused*/, const std::string& /*unused*/, const json::exception& ex)
+    {
+        messages.emplace_back(ex.what());
+        // a limit, so that a reader that does not stop fails the test
+        // instead of making it hang
+        return ++errors < 100;
+    }
+
+    /// whether the events were balanced and every key was followed by a value
+    bool balanced() const
+    {
+        return well_formed && stack.empty();
+    }
+
+    /// builds the value
+    nlohmann::detail::json_sax_dom_parser<BasicJsonType> dom;
+    std::size_t errors = 0;
+    std::vector<std::string> messages {}; // NOLINT(readability-redundant-member-init)
+    std::vector<char> stack {}; // NOLINT(readability-redundant-member-init)
+    bool well_formed = true;
+
+  private:
+    void value()
+    {
+        if (!stack.empty())
+        {
+            if (stack.back() == 'v')
+            {
+                stack.back() = 'o';
+            }
+            else if (stack.back() == 'o')
+            {
+                well_formed = false;
+            }
+        }
+    }
+
+};
+
+using RecoveringParser = BasicRecoveringParser<json>;
+
+struct BinaryParseResult
+{
+    json value;
+    std::size_t errors;
+    std::vector<std::string> messages;
+    bool ok;
+    bool balanced;
+};
+
+BinaryParseResult parse_binary_recovering(const std::vector<std::uint8_t>& input, const json::input_format_t format)
+{
+    json j;
+    RecoveringParser sax(j);
+    const bool ok = json::sax_parse(input, &sax, format);
+    return {j, sax.errors, sax.messages, ok, sax.balanced()};
+}
+
+#if !defined(JSON_NOEXCEPTION)
+/// the message of the exception that reading @a input into a JSON value
+/// throws, or an empty string if reading succeeds
+std::string binary_error_message(const std::vector<std::uint8_t>& input, const json::input_format_t format)
+{
+    try
+    {
+        json _;
+        switch (format)
+        {
+            case json::input_format_t::cbor:
+                _ = json::from_cbor(input);
+                break;
+            case json::input_format_t::msgpack:
+                _ = json::from_msgpack(input);
+                break;
+            case json::input_format_t::ubjson:
+                _ = json::from_ubjson(input);
+                break;
+            case json::input_format_t::bjdata:
+                _ = json::from_bjdata(input);
+                break;
+            case json::input_format_t::bson:
+                _ = json::from_bson(input);
+                break;
+            case json::input_format_t::bon8:
+                _ = json::from_bon8(input);
+                break;
+            case json::input_format_t::json:
+            default:
+                break;
+        }
+    }
+    catch (const json::exception& e)
+    {
+        return e.what();
+    }
+    return "";
+}
+#endif
+
+/// a BSON element: its type, its name, and its value
+std::vector<std::uint8_t> bson_element(const std::uint8_t type, const std::string& name, const std::vector<std::uint8_t>& value)
+{
+    std::vector<std::uint8_t> result = {type};
+    result.insert(result.end(), name.begin(), name.end());
+    result.push_back(0x00);
+    result.insert(result.end(), value.begin(), value.end());
+    return result;
+}
+
+/// a BSON document of the given elements; @a size_offset is added to the
+/// size it declares
+std::vector<std::uint8_t> bson_document(const std::vector<std::vector<std::uint8_t>>& elements, const int size_offset = 0)
+{
+    std::vector<std::uint8_t> body;
+    for (const auto& element : elements)
+    {
+        body.insert(body.end(), element.begin(), element.end());
+    }
+    const auto size = static_cast<std::uint32_t>(static_cast<int>(body.size()) + 5 + size_offset);
+    std::vector<std::uint8_t> result = {static_cast<std::uint8_t>(size & 0xFFu), static_cast<std::uint8_t>((size >> 8u) & 0xFFu),
+                                        static_cast<std::uint8_t>((size >> 16u) & 0xFFu), static_cast<std::uint8_t>((size >> 24u) & 0xFFu)
+                                       };
+    result.insert(result.end(), body.begin(), body.end());
+    result.push_back(0x00);
+    return result;
+}
+
+/// a BSON int32 value
+std::vector<std::uint8_t> bson_int32(const std::int32_t value)
+{
+    const auto u = static_cast<std::uint32_t>(value);
+    return {static_cast<std::uint8_t>(u & 0xFFu), static_cast<std::uint8_t>((u >> 8u) & 0xFFu),
+            static_cast<std::uint8_t>((u >> 16u) & 0xFFu), static_cast<std::uint8_t>((u >> 24u) & 0xFFu)};
+}
+
+/// a BSON string value, whose length is @a length_offset off
+std::vector<std::uint8_t> bson_string(const std::string& value, const std::int32_t length_offset = 0)
+{
+    auto result = bson_int32(static_cast<std::int32_t>(value.size() + 1) + length_offset);
+    result.insert(result.end(), value.begin(), value.end());
+    result.push_back(0x00);
+    return result;
+}
+
+/// @a count bytes of value 0xAB
+std::vector<std::uint8_t> bytes(const std::size_t count)
+{
+    return std::vector<std::uint8_t>(count, 0xAB);
+}
+
+/// the bytes of @a parts, one after the other
+std::vector<std::uint8_t> concatenated(std::initializer_list<std::vector<std::uint8_t>> parts)
+{
+    std::vector<std::uint8_t> result;
+    for (const auto& part : parts)
+    {
+        result.insert(result.end(), part.begin(), part.end());
+    }
+    return result;
+}
+
+/// U+FFFD REPLACEMENT CHARACTER
+std::string replacement_character()
+{
+    return "\xEF\xBF\xBD";
+}
+}  // namespace
+
+TEST_CASE("regression test - #3989 SAX parse_error() returning true")
+{
+    SECTION("binary formats complete what was read before the input ends")
+    {
+        const json j = {{"a", {1, -2, {{"b", "c"}}, json::array()}}, {"d", {{"e", nullptr}, {"f", true}}}, {"g", 1.5}, {"h", json::binary({1, 2, 3})}};
+
+        const std::vector<std::pair<json::input_format_t, std::vector<std::uint8_t>>> encodings =
+        {
+            {json::input_format_t::cbor, json::to_cbor(j)},
+            {json::input_format_t::msgpack, json::to_msgpack(j)},
+            {json::input_format_t::ubjson, json::to_ubjson(j)},
+            {json::input_format_t::ubjson, json::to_ubjson(j, true, true)},
+            {json::input_format_t::bjdata, json::to_bjdata(j)},
+            {json::input_format_t::bjdata, json::to_bjdata(j, true, true)},
+            {json::input_format_t::bson, json::to_bson(j)},
+            {json::input_format_t::bon8, json::to_bon8(j)},
+        };
+
+        for (const auto& encoding : encodings)
+        {
+            const auto format = encoding.first;
+            const auto& bytes = encoding.second;
+            CAPTURE(format)
+
+            // every prefix is truncated input
+            for (std::size_t length = 0; length < bytes.size(); ++length)
+            {
+                CAPTURE(length)
+                const auto result = parse_binary_recovering(std::vector<std::uint8_t>(bytes.begin(), bytes.begin() + static_cast<std::ptrdiff_t>(length)), format);
+                CHECK(!result.ok);
+                CHECK(result.errors == 1);
+                CHECK(result.balanced);
+            }
+
+            // the complete input is read as usual (binary values do not
+            // round-trip through every format, so compare with a plain parse)
+            json expected;
+            nlohmann::detail::json_sax_dom_parser<json> dom(expected);
+            CHECK(json::sax_parse(bytes, &dom, format));
+            const auto complete = parse_binary_recovering(bytes, format);
+            CHECK(complete.ok);
+            CHECK(complete.errors == 0);
+            CHECK(complete.value == expected);
+
+            // a byte after the value
+            auto trailing_bytes = bytes;
+            trailing_bytes.push_back(0x01);
+            const auto trailing = parse_binary_recovering(trailing_bytes, format);
+            CHECK(!trailing.ok);
+            CHECK(trailing.errors == 1);
+            CHECK(trailing.value == expected);
+        }
+    }
+
+    SECTION("containers without an end")
+    {
+        // these made the readers loop, or read on, after the error
+        const auto cbor_array = parse_binary_recovering({0x9F}, json::input_format_t::cbor);
+        CHECK(cbor_array.errors == 1);
+        CHECK(cbor_array.value == json::array());
+
+        const auto cbor_map = parse_binary_recovering({0xBF, 0x61, 'a'}, json::input_format_t::cbor);
+        CHECK(cbor_map.errors == 1);
+        CHECK(cbor_map.value == json({{"a", nullptr}}));
+
+        const auto msgpack_array = parse_binary_recovering({0xDD, 0xFF, 0xFF, 0xFF, 0xFF}, json::input_format_t::msgpack);
+        CHECK(msgpack_array.errors == 1);
+        CHECK(msgpack_array.value == json::array());
+
+        const auto msgpack_map = parse_binary_recovering({0x81, 0xA1, 'a', 0x92, 0x01}, json::input_format_t::msgpack);
+        CHECK(msgpack_map.errors == 1);
+        CHECK(msgpack_map.value == json({{"a", {1}}}));
+    }
+
+    SECTION("BJData ndarray")
+    {
+        // a 2x3 int8 array with two of its six elements; the annotated array
+        // format opens an object and two arrays of its own
+        const auto result = parse_binary_recovering({'[', '$', 'i', '#', '[', '$', 'i', '#', 'i', 2, 2, 3, 1, 2}, json::input_format_t::bjdata);
+        CHECK(result.errors == 1);
+        CHECK(result.balanced);
+        CHECK(result.value == json({{"_ArrayType_", "int8"}, {"_ArraySize_", {2, 3}}, {"_ArrayData_", {1, 2}}}));
+    }
+
+    SECTION("binary formats repair items whose end is known")
+    {
+        struct Repair
+        {
+            json::input_format_t format;
+            std::vector<std::uint8_t> input;
+            json expected;
+            std::size_t errors;
+        };
+
+        const std::vector<Repair> repairs =
+        {
+            // CBOR: tags are ignored (here tag 1 and the self-describe tag 55799)
+            {json::input_format_t::cbor, {0x82, 0xC1, 0x05, 0xD9, 0xD9, 0xF7, 0x06}, {5, 6}, 2},
+            // CBOR: undefined and other simple values become null
+            {json::input_format_t::cbor, {0x84, 0xF7, 0xE0, 0xF8, 0x20, 0x01}, {nullptr, nullptr, nullptr, 1}, 3},
+            // CBOR: members whose key is not a string are skipped, whatever their key and value
+            {json::input_format_t::cbor, {0xA4, 0x01, 0x02, 0x82, 0x01, 0x02, 0xA1, 0x61, 'x', 0x9F, 0xFF, 0xC1, 0x01, 0x5F, 0x41, 0x00, 0xFF, 0x61, 'a', 0x03}, {{"a", 3}}, 3},
+            {json::input_format_t::cbor, {0xBF, 0xF5, 0xBF, 0x61, 'x', 0x7F, 0x61, 'y', 0xFF, 0xFF, 0x61, 'a', 0x03, 0xFF}, {{"a", 3}}, 1},
+            // MessagePack: members whose key is not a string are skipped
+            {json::input_format_t::msgpack, {0x84, 0x01, 0x02, 0x81, 0xA1, 'x', 0x01, 0x92, 0x01, 0x02, 0xD4, 0x01, 0x02, 0xC0, 0xA1, 'a', 0x04}, {{"a", 4}}, 3},
+            // UBJSON: a char that is not ASCII becomes U+FFFD
+            {json::input_format_t::ubjson, {'[', 'C', 0x80, 'C', 'A', ']'}, {replacement_character(), "A"}, 1},
+            // UBJSON: the longest beginning of a high-precision number is kept
+            {json::input_format_t::ubjson, {'[', 'H', 'i', 5, '1', '2', 'a', 'b', 'c', 'H', 'i', 2, '1', '.', 'H', 'i', 3, 'a', 'b', 'c', 'H', 'i', 3, '4', '.', '5', ']'}, {12, 1, nullptr, 4.5}, 3},
+            // BJData, too
+            {json::input_format_t::bjdata, {'[', 'C', 0xFF, 'H', 'i', 2, '-', '1', 'H', 'i', 2, '-', 'x', ']'}, {replacement_character(), -1, nullptr}, 2},
+            // a NUL ends a high-precision number, as it ends JSON text
+            {json::input_format_t::ubjson, {'[', 'H', 'i', 4, '1', '2', 0, '9', 'H', 'i', 2, 0, '1', 'i', 3, ']'}, {12, nullptr, 3}, 2},
+            // BON8: members whose key is not a string are skipped
+            {json::input_format_t::bon8, {0x89, 0x91, 0x92, 0xC9, 0x40, 0x82, 0x91, 0x92, 0x61, 0x93}, {{"a", 3}}, 2},
+            {json::input_format_t::bon8, {0x8B, 0x91, 0x85, 0x91, 0xFE, 0xFA, 0x8B, 'x', 0x91, 0xFE, 0x61, 0x93, 0xFE}, {{"a", 3}}, 2},
+            // BSON: elements of types the library does not read become null
+            {
+                json::input_format_t::bson, bson_document(
+                {
+                    bson_element(0x07, "_id", bytes(12)),                         // ObjectId
+                    bson_element(0x09, "date", bytes(8)),                         // UTC datetime
+                    bson_element(0x13, "decimal", bytes(16)),                     // 128-bit decimal
+                    bson_element(0x0B, "regex", {'a', '+', 0, 'i', 0}),           // regular expression
+                    bson_element(0x0D, "code", bson_string("f()")),               // JavaScript code
+                    bson_element(0x0E, "symbol", bson_string("s")),               // symbol
+                    bson_element(0x0C, "pointer", concatenated({bson_string("c"), bytes(12)})), // DBPointer
+                    bson_element(0x0F, "scope", concatenated({bson_int32(15), bson_string("g"), bson_document({})})), // code with scope
+                    bson_element(0x06, "undefined", {}),                          // undefined
+                    bson_element(0xFF, "min", {}),                                // min key
+                    bson_element(0x7F, "max", {}),                                // max key
+                    bson_element(0x10, "z", bson_int32(7)),
+                }),
+                {{"_id", nullptr}, {"date", nullptr}, {"decimal", nullptr}, {"regex", nullptr}, {"code", nullptr}, {"symbol", nullptr}, {"pointer", nullptr}, {"scope", nullptr}, {"undefined", nullptr}, {"min", nullptr}, {"max", nullptr}, {"z", 7}},
+                11
+            },
+            // BSON: an element of an unknown type becomes null, and the rest of its document is skipped
+            {
+                json::input_format_t::bson, bson_document(
+                {
+                    bson_element(0x03, "inner", bson_document({bson_element(0x10, "a", bson_int32(1)), bson_element(0x42, "x", bytes(3)), bson_element(0x10, "b", bson_int32(2))})),
+                    bson_element(0x04, "array", bson_document({bson_element(0x10, "0", bson_int32(1)), bson_element(0x42, "1", bytes(3))})),
+                    bson_element(0x10, "after", bson_int32(3)),
+                }),
+                {{"inner", {{"a", 1}, {"x", nullptr}}}, {"array", {1, nullptr}}, {"after", 3}},
+                2
+            },
+            // BSON: so does a string or byte array whose length cannot be right
+            {
+                json::input_format_t::bson, bson_document(
+                {
+                    bson_element(0x03, "inner", bson_document({bson_element(0x02, "s", bson_string("abc", -10)), bson_element(0x10, "b", bson_int32(2))})),
+                    bson_element(0x03, "bin", bson_document({bson_element(0x05, "b", concatenated({bson_int32(-1), bytes(1)})), bson_element(0x10, "b", bson_int32(2))})),
+                    bson_element(0x10, "after", bson_int32(3)),
+                }),
+                {{"inner", {{"s", nullptr}}}, {"bin", {{"b", nullptr}}}, {"after", 3}},
+                2
+            },
+            // BSON: a string without its terminator, and a document whose size does not match, are kept
+            {
+                json::input_format_t::bson, bson_document(
+                {
+                    bson_element(0x02, "s", {2, 0, 0, 0, 'a', 'X'}),
+                    bson_element(0x03, "inner", bson_document({bson_element(0x10, "a", bson_int32(1))}, 1)),
+                }),
+                {{"s", "a"}, {"inner", {{"a", 1}}}},
+                2
+            },
+        };
+
+        for (const auto& repair : repairs)
+        {
+            CAPTURE(repair.format)
+            CAPTURE(repair.input)
+            const auto result = parse_binary_recovering(repair.input, repair.format);
+            CHECK(!result.ok);
+            CHECK(result.balanced);
+            CHECK(result.errors == repair.errors);
+            CHECK(result.value == repair.expected);
+            REQUIRE(!result.messages.empty());
+#if !defined(JSON_NOEXCEPTION)
+            // the first error is the one reported without recovering; under
+            // JSON_NOEXCEPTION, reading without recovering aborts instead of
+            // throwing, so there is no message to compare with
+            CHECK(result.messages.front() == binary_error_message(repair.input, repair.format));
+#endif
+        }
+    }
+
+    SECTION("binary formats repair numbers that are out of range")
+    {
+        // CBOR: a double too large for a float number_float_t
+        float_json cbor;
+        BasicRecoveringParser<float_json> sax(cbor);
+        const std::vector<std::uint8_t> cbor_input = {0x82, 0xFB, 0x7E, 0x37, 0xE4, 0x3C, 0x88, 0x00, 0x75, 0x9C, 0x01}; // [1e300, 1]
+        CHECK(!float_json::sax_parse(cbor_input, &sax, float_json::input_format_t::cbor));
+        CHECK(sax.errors == 1);
+        CHECK(sax.messages.front() == "[json.exception.out_of_range.406] syntax error while parsing CBOR value: number overflow");
+        REQUIRE(cbor.size() == 2);
+        CHECK(std::isinf(cbor[0].get<float>()));
+        CHECK(cbor[1] == 1);
+
+        // UBJSON: a high-precision number too large for number_float_t
+        const auto ubjson = parse_binary_recovering({'H', 'i', 5, '1', 'e', '9', '9', '9'}, json::input_format_t::ubjson);
+        CHECK(ubjson.errors == 1);
+        CHECK(ubjson.value.is_number_float());
+        CHECK(std::isinf(ubjson.value.get<double>()));
+    }
+
+    SECTION("binary formats stop where the end of an item is not known")
+    {
+        // a byte that begins no item
+        const auto cbor = parse_binary_recovering({0x82, 0x01, 0x1C, 0x02}, json::input_format_t::cbor);
+        CHECK(cbor.errors == 1);
+        CHECK(cbor.value == json({1}));
+
+        // a key that is no item: the unused MessagePack byte, a CBOR break
+        // in a map of known size, and the end of a BON8 container
+        const auto msgpack = parse_binary_recovering({0x82, 0xA1, 'a', 0x01, 0xC1, 0x02}, json::input_format_t::msgpack);
+        CHECK(msgpack.errors == 1);
+        CHECK(msgpack.value == json({{"a", 1}}));
+        const auto cbor_break = parse_binary_recovering({0xA2, 0x61, 'a', 0x01, 0xFF, 0x02}, json::input_format_t::cbor);
+        CHECK(cbor_break.errors == 1);
+        CHECK(cbor_break.value == json({{"a", 1}}));
+        const auto bon8 = parse_binary_recovering({0x88, 0x61, 0x91, 0xFE}, json::input_format_t::bon8);
+        CHECK(bon8.errors == 1);
+        CHECK(bon8.value == json({{"a", 1}}));
+
+        // an indefinite-length string inside an indefinite-length string
+        const auto nested = parse_binary_recovering({0x82, 0x01, 0x7F, 0x7F, 0x61, 'a', 0xFF, 0xFF}, json::input_format_t::cbor);
+        CHECK(nested.errors == 1);
+        CHECK(nested.value == json({1}));
+
+        // a BJData ndarray whose element type has no name: the object that
+        // holds the ndarray was already begun
+        const auto ndarray = parse_binary_recovering({'[', '$', 0x01, '#', '[', '$', 'i', '#', 'i', 2, 2, 3}, json::input_format_t::bjdata);
+        CHECK(ndarray.errors == 1);
+        CHECK(ndarray.balanced);
+        CHECK(ndarray.value == json::object());
+
+        // a skipped member that the input ends in
+        const auto truncated = parse_binary_recovering({0xA2, 0x01, 0x82, 0x01}, json::input_format_t::cbor);
+        CHECK(truncated.errors == 2);
+        CHECK(truncated.balanced);
+        CHECK(truncated.value == json::object());
+
+        // a BSON element of an unknown type in a document whose size cannot be right
+        const auto bson = parse_binary_recovering(bson_document({bson_element(0x10, "a", bson_int32(1)), bson_element(0x42, "x", bytes(3))}, -10), json::input_format_t::bson);
+        CHECK(bson.errors == 1);
+        CHECK(bson.value == json({{"a", 1}, {"x", nullptr}}));
+    }
+
+    SECTION("changed bytes in binary input")
+    {
+        const json j = {{"a", {1, -2, {{"b", "c"}}, json::array()}}, {"d", {{"e", nullptr}, {"f", true}}}, {"g", 1.5}, {"h", json::binary({1, 2, 3})}, {"i", "\xC3\xA4"}};
+
+        const std::vector<std::pair<json::input_format_t, std::vector<std::uint8_t>>> encodings =
+        {
+            {json::input_format_t::cbor, json::to_cbor(j)},
+            {json::input_format_t::msgpack, json::to_msgpack(j)},
+            {json::input_format_t::ubjson, json::to_ubjson(j)},
+            {json::input_format_t::ubjson, json::to_ubjson(j, true, true)},
+            {json::input_format_t::bjdata, json::to_bjdata(j)},
+            {json::input_format_t::bjdata, json::to_bjdata(j, true, true)},
+            {json::input_format_t::bson, json::to_bson(j)},
+            {json::input_format_t::bon8, json::to_bon8(j)},
+        };
+        const std::vector<std::uint8_t> replacements = {0x00, 0x01, 0x7F, 0x80, 0xC1, 0xD9, 0xE0, 0xF7, 0xFE, 0xFF};
+
+        for (const auto& encoding : encodings)
+        {
+            const auto format = encoding.first;
+            const auto& original = encoding.second;
+            CAPTURE(format)
+
+            std::vector<std::vector<std::uint8_t>> inputs;
+            for (std::size_t position = 0; position < original.size(); ++position)
+            {
+                for (const auto replacement : replacements)
+                {
+                    auto changed = original;
+                    changed[position] = replacement;
+                    inputs.push_back(changed);
+                }
+                auto removed = original;
+                removed.erase(removed.begin() + static_cast<std::ptrdiff_t>(position));
+                inputs.push_back(removed);
+            }
+
+            for (const auto& input : inputs)
+            {
+                CAPTURE(input)
+                const auto result = parse_binary_recovering(input, format);
+                CHECK(result.balanced);
+                CHECK(result.errors <= input.size() + 1);
+#if !defined(JSON_NOEXCEPTION)
+                // an error is reported exactly if reading into a JSON value
+                // fails, and the first one is the same (under JSON_NOEXCEPTION,
+                // that reading aborts instead of throwing)
+                const auto message = binary_error_message(input, format);
+                CHECK(result.ok == message.empty());
+                if (!result.ok && result.errors < 100)
+                {
+                    CHECK(result.messages.front() == message);
+                }
+#endif
+            }
+        }
+    }
+
+    SECTION("JSON text")
+    {
+        // the parser stopped, but reported success
+        json j;
+        RecoveringParser sax(j);
+        CHECK(!json::sax_parse("[1,2,3,]", &sax));
+        CHECK(sax.errors == 1);
+        CHECK(j == json({1, 2, 3}));
+    }
+
+    SECTION("the SAX parsers of the library stop")
+    {
+        json _;
+        CHECK(json::from_cbor(std::vector<std::uint8_t> {0x9F}, true, false).is_discarded());
+        CHECK_THROWS_WITH_AS(_ = json::from_cbor(std::vector<std::uint8_t> {0x9F}), "[json.exception.parse_error.110] parse error at byte 2: syntax error while parsing CBOR value: unexpected end of input", json::parse_error&);
+        CHECK(json::parse("[1,2,3,]", nullptr, false).is_discarded());
+        CHECK(!json::accept("[1,2,3,]"));
+    }
+}
+
+
+TEST_CASE("issue #5676 - SAX parsing of CBOR tags")
+{
+    const json expected = json::binary({1, 2, 3}, 42);
+    const auto cbor = json::to_cbor(expected);
+
+    nlohmann::detail::json_sax_acceptor<json> acceptor;
+    CHECK_FALSE(json::sax_parse(cbor, &acceptor, json::input_format_t::cbor));
+    CHECK_FALSE(json::sax_parse(cbor, &acceptor, json::input_format_t::cbor,
+                                true, false, false, json::cbor_tag_handler_t::error));
+
+    CHECK(json::sax_parse(cbor, &acceptor, json::input_format_t::cbor,
+                          true, false, false, json::cbor_tag_handler_t::ignore));
+
+    json parsed;
+    nlohmann::detail::json_sax_dom_parser<json, nlohmann::detail::string_input_adapter_type> sax(parsed);
+    CHECK(json::sax_parse(cbor, &sax, json::input_format_t::cbor,
+                          true, false, false, json::cbor_tag_handler_t::store));
+    CHECK(parsed == expected);
+
+    json iterator_parsed;
+    nlohmann::detail::json_sax_dom_parser<json, nlohmann::detail::string_input_adapter_type> iterator_sax(iterator_parsed);
+    CHECK(json::sax_parse(cbor.begin(), cbor.end(), &iterator_sax, json::input_format_t::cbor,
+                          true, false, false, json::cbor_tag_handler_t::store));
+    CHECK(iterator_parsed == expected);
+
+#ifndef JSON_TEST_DEPRECATED_FUNCTIONS_DELETED
+    json span_parsed;
+    nlohmann::detail::json_sax_dom_parser<json, nlohmann::detail::string_input_adapter_type> span_sax(span_parsed);
+    CHECK(json::sax_parse(nlohmann::detail::span_input_adapter(cbor.data(), cbor.size()), &span_sax,
+                          json::input_format_t::cbor, true, false, false, json::cbor_tag_handler_t::store));
+    CHECK(span_parsed == expected);
+#endif
+
+    const std::string text = "null";
+    CHECK(json::sax_parse(text, &acceptor, json::input_format_t::json,
+                          true, false, false, json::cbor_tag_handler_t::store));
+    CHECK(json::sax_parse(text.begin(), text.end(), &acceptor, json::input_format_t::json,
+                          true, false, false, json::cbor_tag_handler_t::store));
+#ifndef JSON_TEST_DEPRECATED_FUNCTIONS_DELETED
+    CHECK(json::sax_parse(nlohmann::detail::span_input_adapter(text.data(), text.size()), &acceptor,
+                          json::input_format_t::json, true, false, false, json::cbor_tag_handler_t::store));
+#endif
+}
+
+
+TEST_CASE("MessagePack SAX aborts")
+{
+    SECTION("start_array(len)")
+    {
+        std::vector<uint8_t> const v = {0x93, 0x01, 0x02, 0x03};
+        SaxCountdown scp(0);
+        CHECK(!json::sax_parse(v, &scp, json::input_format_t::msgpack));
+    }
+
+    SECTION("start_object(len)")
+    {
+        std::vector<uint8_t> const v = {0x81, 0xa3, 0x66, 0x6F, 0x6F, 0xc2};
+        SaxCountdown scp(0);
+        CHECK(!json::sax_parse(v, &scp, json::input_format_t::msgpack));
+    }
+
+    SECTION("key()")
+    {
+        std::vector<uint8_t> const v = {0x81, 0xa3, 0x66, 0x6F, 0x6F, 0xc2};
+        SaxCountdown scp(1);
+        CHECK(!json::sax_parse(v, &scp, json::input_format_t::msgpack));
+    }
+}
+
+TEST_CASE("issue #5405 - a user-defined SAX consumer is unaffected by the internal DOM reserve optimization")
+{
+    // the reserve() call is local to json_sax_dom_parser / json_sax_dom_callback_parser;
+    // a custom SAX consumer that does not touch a DOM array sees identical events
+    json j = json::array();
+    for (int i = 0; i < 100; ++i)
+    {
+        j.push_back(i);
+    }
+    const auto packed = json::to_msgpack(j);
+
+    SaxCountdown scp(1000000); // large enough to never trigger an abort
+    CHECK(json::sax_parse(packed, &scp, json::input_format_t::msgpack));
+}
+
+TEST_CASE("MessagePack nesting does not consume the call stack - SAX interface")
+{
+    // see the test case of the same name in unit-msgpack.cpp (#5104)
+    std::vector<uint8_t> input(300000, 0x91);
+    input.push_back(0x01); // innermost value
+
+    SaxCountdown accept_all(600001);
+    CHECK(json::sax_parse(input, &accept_all, json::input_format_t::msgpack));
+}
+
+TEST_CASE("MessagePack SAX parsing stops at every event")
+{
+    // Containers are opened and closed by the loop that reads them; a SAX
+    // handler that rejects any event - including the end of a nested
+    // container - must stop the parse right there.
+    const auto count_events = [](const std::vector<std::uint8_t>& input)
+    {
+        int events = 0;
+        while (true)
+        {
+            SaxCountdown scp(events);
+            if (json::sax_parse(input, &scp, json::input_format_t::msgpack))
+            {
+                return events;
+            }
+            ++events;
+            REQUIRE(events < 1000);
+        }
+    };
+
+    // 20 events: every container kind closes inside another one
+    const json j = json::parse(R"({"a": [1, {"b": []}], "c": {"d": [[2]]}})");
+    CHECK(count_events(json::to_msgpack(j)) == 20);
+}
+
+DOCTEST_CLANG_SUPPRESS_WARNING_POP